Commit 8b7ca38

@@ -0,0 +1,275 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"github.com/chzyer/readline"
+	"golang.org/x/sync/errgroup"
+
+	"goVNC/internal/cli"
+	"goVNC/pkg/input"
+	"goVNC/pkg/rfb"
+	"goVNC/pkg/transport"
+	"goVNC/pkg/web"
+)
+
+func main() {
+	if err := run(); err != nil {
+		slog.Error("fatal", slog.String("error", err.Error()))
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	// Parse flags
+	cfg, err := cli.ParseFlags(os.Args[1:])
+	if err != nil {
+		return err
+	}
+
+	// Configure logging
+	setupLogging(cfg.Output.Verbose, cfg.Output.Silent)
+
+	// Validate URL
+	if cfg.URL == "" {
+		return fmt.Errorf("no URL provided. Use: govnc <URL> or set VNC_URL")
+	}
+
+	// Create context with signal handling
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Handle signals
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigCh
+		slog.Info("shutting down...")
+		cancel()
+	}()
+
+	// Connect to VNC server
+	slog.Info("connecting", slog.String("url", cfg.URL))
+
+	dialer := transport.NewWebSocketDialer()
+	dialOpts := cfg.Connection.ToDialOptions()
+
+	t, err := dialer.Dial(ctx, cfg.URL, dialOpts)
+	if err != nil {
+		return fmt.Errorf("connecting: %w", err)
+	}
+	defer t.Close()
+
+	// Create RFB client
+	clientCfg := cfg.VNC.ToClientConfig()
+	client := rfb.NewClient(t, clientCfg)
+
+	// Connect and handshake
+	session, err := client.Connect(ctx)
+	if err != nil {
+		return fmt.Errorf("handshake: %w", err)
+	}
+
+	slog.Info("connected",
+		slog.String("name", session.Name),
+		slog.Int("width", int(session.Width)),
+		slog.Int("height", int(session.Height)))
+
+	// Handle one-shot modes
+	if cfg.Input.TypeText != "" {
+		return handleTypeAndExit(ctx, client, cfg.Input.TypeText)
+	}
+
+	if cfg.Clipboard.ClipSend != "" {
+		return handleClipSendAndExit(ctx, client, cfg.Clipboard.ClipSend)
+	}
+
+	// Server mode
+	if cfg.Server.HTTPAddr != "" {
+		return runServerMode(ctx, client, cfg)
+	}
+
+	// Interactive mode
+	return runInteractiveMode(ctx, client, cfg, session)
+}
+
+func setupLogging(verbose int, silent bool) {
+	var level slog.Level
+	if silent {
+		level = slog.LevelError + 1 // Suppress all logs
+	} else {
+		switch verbose {
+		case 0:
+			level = slog.LevelInfo
+		case 1:
+			level = slog.LevelDebug
+		default:
+			level = slog.LevelDebug - 4 // Trace level
+		}
+	}
+
+	handler := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
+		Level: level,
+	})
+	slog.SetDefault(slog.New(handler))
+}
+
+func handleTypeAndExit(ctx context.Context, client *rfb.Client, text string) error {
+	slog.Info("typing", slog.Int("len", len(text)))
+	if err := client.Type(ctx, text); err != nil {
+		return fmt.Errorf("typing: %w", err)
+	}
+	slog.Info("done")
+	return nil
+}
+
+func handleClipSendAndExit(ctx context.Context, client *rfb.Client, text string) error {
+	// Handle @file syntax
+	if strings.HasPrefix(text, "@") {
+		data, err := os.ReadFile(text[1:])
+		if err != nil {
+			return fmt.Errorf("reading file: %w", err)
+		}
+		text = string(data)
+	}
+
+	slog.Info("sending clipboard", slog.Int("len", len(text)))
+	if err := client.SetClipboard(ctx, text); err != nil {
+		return fmt.Errorf("sending clipboard: %w", err)
+	}
+	slog.Info("done")
+	return nil
+}
+
+func runServerMode(ctx context.Context, client *rfb.Client, cfg *cli.Config) error {
+	serverCfg := cfg.Server.ToServerConfig()
+	server := web.NewServer(client, serverCfg)
+
+	// Set up clipboard handler if output dir specified
+	if cfg.Clipboard.ClipOutDir != "" {
+		clipMgr, err := input.NewClipboardManager(client, &input.ClipboardConfig{
+			SaveDir: cfg.Clipboard.ClipOutDir,
+		})
+		if err != nil {
+			return fmt.Errorf("creating clipboard manager: %w", err)
+		}
+		client.OnClipboard(clipMgr.OnReceive)
+	}
+
+	g, ctx := errgroup.WithContext(ctx)
+
+	// Run VNC message listener
+	g.Go(func() error {
+		return client.Listen(ctx)
+	})
+
+	// Run web server
+	g.Go(func() error {
+		return server.ListenAndServe(ctx)
+	})
+
+	slog.Info("server mode started",
+		slog.String("http", cfg.Server.HTTPAddr),
+		slog.String("api", cfg.Server.APIPrefix))
+
+	return g.Wait()
+}
+
+func runInteractiveMode(ctx context.Context, client *rfb.Client, cfg *cli.Config, session *rfb.Session) error {
+	g, ctx := errgroup.WithContext(ctx)
+
+	// Set up clipboard manager
+	clipMgr, err := input.NewClipboardManager(client, &input.ClipboardConfig{
+		WatchDir: cfg.Clipboard.ClipInDir,
+		SaveDir:  cfg.Clipboard.ClipOutDir,
+	})
+	if err != nil {
+		return fmt.Errorf("creating clipboard manager: %w", err)
+	}
+	client.OnClipboard(clipMgr.OnReceive)
+
+	// Run VNC message listener
+	g.Go(func() error {
+		return client.Listen(ctx)
+	})
+
+	// Run clipboard watcher if configured
+	if cfg.Clipboard.ClipInDir != "" {
+		g.Go(func() error {
+			return clipMgr.Start(ctx)
+		})
+	}
+
+	// Run stdin reader
+	if cfg.Input.InputFile == "" || cfg.Input.InputFile == "-" {
+		g.Go(func() error {
+			return readStdin(ctx, client, session.Name)
+		})
+	} else if cfg.Input.InputFile != "" {
+		g.Go(func() error {
+			return readInputFile(ctx, client, cfg.Input.InputFile)
+		})
+	}
+
+	return g.Wait()
+}
+
+func readStdin(ctx context.Context, client *rfb.Client, serverName string) error {
+	prompt := serverName + "> "
+	rl, err := readline.NewEx(&readline.Config{
+		Prompt:          prompt,
+		HistoryFile:     ".govnc_history",
+		InterruptPrompt: "^C",
+		EOFPrompt:       "exit",
+	})
+	if err != nil {
+		return fmt.Errorf("creating readline: %w", err)
+	}
+	defer rl.Close()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		default:
+		}
+
+		line, err := rl.Readline()
+		if err == readline.ErrInterrupt {
+			continue
+		}
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return fmt.Errorf("reading line: %w", err)
+		}
+
+		line = line + "\n"
+		slog.Debug("typing", slog.String("line", strings.TrimSpace(line)))
+		if err := client.Type(ctx, line); err != nil {
+			return fmt.Errorf("typing line: %w", err)
+		}
+	}
+}
+
+func readInputFile(ctx context.Context, client *rfb.Client, path string) error {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("reading input file: %w", err)
+	}
+
+	slog.Info("typing from file", slog.String("file", path), slog.Int("len", len(data)))
+	if err := client.Type(ctx, string(data)); err != nil {
+		return fmt.Errorf("typing: %w", err)
+	}
+
+	return nil
+}

@@ -0,0 +1,239 @@
+// Package cli provides CLI infrastructure for govnc.
+package cli
+
+import (
+	"net/http"
+	"time"
+
+	"goVNC/pkg/proxy"
+	"goVNC/pkg/rfb"
+	"goVNC/pkg/transport"
+	"goVNC/pkg/web"
+)
+
+// Config holds all CLI configuration.
+type Config struct {
+	// Target WebSocket URL
+	URL string
+
+	// Connection options
+	Connection ConnectionConfig
+
+	// VNC session options
+	VNC VNCConfig
+
+	// Input options
+	Input InputConfig
+
+	// Clipboard options
+	Clipboard ClipboardConfig
+
+	// Server mode options
+	Server ServerConfig
+
+	// Output options
+	Output OutputConfig
+}
+
+// ConnectionConfig holds connection-related settings.
+type ConnectionConfig struct {
+	// Headers to send with the connection (repeatable).
+	Headers http.Header
+
+	// Cookie string to send.
+	Cookie string
+
+	// UserAgent to send.
+	UserAgent string
+
+	// Proxy URL for upstream proxy.
+	Proxy string
+
+	// ConnectTimeout for connection establishment.
+	ConnectTimeout time.Duration
+
+	// Insecure skips TLS verification.
+	Insecure bool
+}
+
+// VNCConfig holds VNC-specific settings.
+type VNCConfig struct {
+	// User for VNC authentication (user:password format).
+	User string
+
+	// Password for VNC authentication.
+	Password string
+
+	// AuthNone forces no authentication.
+	AuthNone bool
+
+	// Shared requests a shared session.
+	Shared bool
+
+	// Exclusive requests an exclusive session.
+	Exclusive bool
+
+	// Encodings to request.
+	Encodings []int32
+}
+
+// InputConfig holds input-related settings.
+type InputConfig struct {
+	// InputFile to read input from (- for stdin).
+	InputFile string
+
+	// TypeText to type and exit.
+	TypeText string
+
+	// KeyDelay between keystrokes in milliseconds.
+	KeyDelay int
+}
+
+// ClipboardConfig holds clipboard-related settings.
+type ClipboardConfig struct {
+	// ClipInDir to watch for outgoing clipboard files.
+	ClipInDir string
+
+	// ClipOutDir to save incoming clipboard files.
+	ClipOutDir string
+
+	// ClipSend text to send to clipboard and exit.
+	ClipSend string
+}
+
+// ServerConfig holds server mode settings.
+type ServerConfig struct {
+	// HTTPAddr to start HTTP/WS server on.
+	HTTPAddr string
+
+	// ProxyMode for client sessions.
+	ProxyMode string
+
+	// MaxClients for concurrent WebSocket clients.
+	MaxClients int
+
+	// NoVNCPath for static noVNC files.
+	NoVNCPath string
+
+	// APIPrefix for API routes.
+	APIPrefix string
+
+	// CORSOrigin for CORS headers.
+	CORSOrigin string
+}
+
+// OutputConfig holds output-related settings.
+type OutputConfig struct {
+	// Verbose level (0-3).
+	Verbose int
+
+	// Silent suppresses output.
+	Silent bool
+
+	// OutputFile to write to.
+	OutputFile string
+}
+
+// DefaultConfig returns a Config with sensible defaults.
+func DefaultConfig() *Config {
+	return &Config{
+		Connection: ConnectionConfig{
+			Headers:        make(http.Header),
+			UserAgent:      "govnc/1.0",
+			ConnectTimeout: 30 * time.Second,
+		},
+		VNC: VNCConfig{
+			Shared:    true,
+			Encodings: rfb.DefaultEncodings(),
+		},
+		Server: ServerConfig{
+			HTTPAddr:   ":8080",
+			ProxyMode:  "shared",
+			MaxClients: 10,
+			APIPrefix:  "/api",
+			CORSOrigin: "*",
+		},
+	}
+}
+
+// ToDialOptions converts ConnectionConfig to transport.DialOptions.
+func (c *ConnectionConfig) ToDialOptions() *transport.DialOptions {
+	opts := transport.NewDialOptions()
+	opts.Headers = c.Headers.Clone()
+	if c.Cookie != "" {
+		opts.AddHeader("Cookie", c.Cookie)
+	}
+	if c.UserAgent != "" {
+		opts.AddHeader("User-Agent", c.UserAgent)
+	}
+	opts.Timeout = c.ConnectTimeout
+	opts.Proxy = c.Proxy
+	// TODO: Handle Insecure flag with TLS config
+	return opts
+}
+
+// ToHandshakeConfig converts VNCConfig to rfb.HandshakeConfig.
+func (c *VNCConfig) ToHandshakeConfig() *rfb.HandshakeConfig {
+	cfg := rfb.DefaultHandshakeConfig()
+
+	// Determine shared mode
+	if c.Exclusive {
+		cfg.SharedSession = false
+	} else if c.Shared {
+		cfg.SharedSession = true
+	}
+
+	// Set password if provided
+	if c.Password != "" {
+		cfg.Password = c.Password
+	}
+
+	// Add VNC auth if password is provided
+	if c.Password != "" && !c.AuthNone {
+		cfg.AllowedSecurityTypes = []rfb.SecurityType{
+			rfb.SecurityTypeNone,
+			rfb.SecurityTypeVNCAuth,
+		}
+	}
+
+	return cfg
+}
+
+// ToClientConfig converts VNCConfig to rfb.ClientConfig.
+func (c *VNCConfig) ToClientConfig() *rfb.ClientConfig {
+	cfg := rfb.DefaultClientConfig()
+	cfg.Handshake = c.ToHandshakeConfig()
+	if len(c.Encodings) > 0 {
+		cfg.Encodings = c.Encodings
+	}
+	return cfg
+}
+
+// ToServerConfig converts ServerConfig to web.ServerConfig.
+func (c *ServerConfig) ToServerConfig() *web.ServerConfig {
+	cfg := web.DefaultServerConfig()
+	if c.HTTPAddr != "" {
+		cfg.ListenAddr = c.HTTPAddr
+	}
+	if c.APIPrefix != "" {
+		cfg.APIPrefix = c.APIPrefix
+	}
+	if c.NoVNCPath != "" {
+		cfg.NoVNCPath = c.NoVNCPath
+	}
+	if c.CORSOrigin != "" {
+		cfg.CORSOrigin = c.CORSOrigin
+	}
+	if c.MaxClients > 0 {
+		cfg.MaxClients = c.MaxClients
+	}
+
+	switch c.ProxyMode {
+	case "isolated":
+		cfg.ProxyMode = proxy.IsolatedMode
+	default:
+		cfg.ProxyMode = proxy.SharedMode
+	}
+
+	return cfg
+}

@@ -0,0 +1,258 @@
+package cli
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+)
+
+// headerList is a flag.Value that collects multiple -H flags.
+type headerList []string
+
+func (h *headerList) String() string {
+	return strings.Join(*h, ", ")
+}
+
+func (h *headerList) Set(value string) error {
+	*h = append(*h, value)
+	return nil
+}
+
+// ParseFlags parses command-line flags and returns a Config.
+func ParseFlags(args []string) (*Config, error) {
+	cfg := DefaultConfig()
+
+	fs := flag.NewFlagSet("govnc", flag.ContinueOnError)
+
+	// Custom usage
+	fs.Usage = func() {
+		fmt.Fprint(os.Stderr, usage)
+	}
+
+	// Connection flags
+	var headers headerList
+	fs.Var(&headers, "H", "Add custom header (repeatable)")
+	fs.Var(&headers, "header", "Add custom header (repeatable)")
+	fs.StringVar(&cfg.Connection.Cookie, "b", "", "Send cookies")
+	fs.StringVar(&cfg.Connection.Cookie, "cookie", "", "Send cookies")
+	fs.StringVar(&cfg.Connection.UserAgent, "A", "govnc/1.0", "User-Agent header")
+	fs.StringVar(&cfg.Connection.UserAgent, "user-agent", "govnc/1.0", "User-Agent header")
+	fs.StringVar(&cfg.Connection.Proxy, "x", "", "Use proxy (http, socks5)")
+	fs.StringVar(&cfg.Connection.Proxy, "proxy", "", "Use proxy (http, socks5)")
+
+	var connectTimeout int
+	fs.IntVar(&connectTimeout, "connect-timeout", 30, "Connection timeout in seconds")
+	fs.BoolVar(&cfg.Connection.Insecure, "k", false, "Skip TLS verification")
+	fs.BoolVar(&cfg.Connection.Insecure, "insecure", false, "Skip TLS verification")
+
+	// Authentication flags
+	fs.StringVar(&cfg.VNC.User, "u", "", "VNC authentication (user:password)")
+	fs.StringVar(&cfg.VNC.User, "user", "", "VNC authentication (user:password)")
+	fs.BoolVar(&cfg.VNC.AuthNone, "auth-none", false, "Force no authentication")
+
+	// VNC flags
+	fs.BoolVar(&cfg.VNC.Shared, "shared", true, "Request shared session")
+	fs.BoolVar(&cfg.VNC.Exclusive, "exclusive", false, "Request exclusive session")
+
+	var encodings string
+	fs.StringVar(&encodings, "encoding", "", "Comma-separated encodings")
+
+	// Input flags
+	fs.StringVar(&cfg.Input.InputFile, "i", "", "Read input from file (- for stdin)")
+	fs.StringVar(&cfg.Input.InputFile, "input", "", "Read input from file (- for stdin)")
+	fs.StringVar(&cfg.Input.TypeText, "type", "", "Type string and exit")
+	fs.IntVar(&cfg.Input.KeyDelay, "delay", 0, "Delay between keystrokes in ms")
+
+	// Clipboard flags
+	fs.StringVar(&cfg.Clipboard.ClipInDir, "clip-in", "", "Watch directory for outgoing clipboard")
+	fs.StringVar(&cfg.Clipboard.ClipOutDir, "clip-out", "", "Save incoming clipboard to directory")
+	fs.StringVar(&cfg.Clipboard.ClipSend, "clip-send", "", "Send clipboard text and exit")
+
+	// Server flags
+	fs.StringVar(&cfg.Server.HTTPAddr, "http", "", "Start HTTP/WS server on address")
+	fs.StringVar(&cfg.Server.ProxyMode, "proxy-mode", "shared", "Client session mode (shared|isolated)")
+	fs.IntVar(&cfg.Server.MaxClients, "max-clients", 10, "Max concurrent WebSocket clients")
+	fs.StringVar(&cfg.Server.NoVNCPath, "novnc-path", "", "Path to noVNC static files")
+	fs.StringVar(&cfg.Server.APIPrefix, "api-prefix", "/api", "API route prefix")
+	fs.StringVar(&cfg.Server.CORSOrigin, "cors-origin", "*", "CORS allowed origin")
+
+	// Output flags
+	fs.IntVar(&cfg.Output.Verbose, "v", 0, "Verbose output (use multiple times for more)")
+	fs.BoolVar(&cfg.Output.Silent, "s", false, "Silent mode")
+	fs.BoolVar(&cfg.Output.Silent, "silent", false, "Silent mode")
+	fs.StringVar(&cfg.Output.OutputFile, "o", "", "Write output to file")
+	fs.StringVar(&cfg.Output.OutputFile, "output", "", "Write output to file")
+
+	// Help flags
+	var showHelp bool
+	fs.BoolVar(&showHelp, "h", false, "Show help")
+	fs.BoolVar(&showHelp, "help", false, "Show help")
+
+	var showVersion bool
+	fs.BoolVar(&showVersion, "version", false, "Show version")
+
+	// Parse flags
+	if err := fs.Parse(args); err != nil {
+		return nil, err
+	}
+
+	if showHelp {
+		fs.Usage()
+		os.Exit(0)
+	}
+
+	if showVersion {
+		fmt.Println("govnc version 1.0.0")
+		os.Exit(0)
+	}
+
+	// Process headers
+	for _, h := range headers {
+		parts := strings.SplitN(h, ":", 2)
+		if len(parts) == 2 {
+			cfg.Connection.Headers.Add(strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]))
+		}
+	}
+
+	// Process timeout (connectTimeout is in seconds, convert to time.Duration)
+	if connectTimeout > 0 {
+		cfg.Connection.ConnectTimeout = time.Duration(connectTimeout) * time.Second
+	}
+
+	// Process user:password
+	if cfg.VNC.User != "" {
+		parts := strings.SplitN(cfg.VNC.User, ":", 2)
+		if len(parts) == 2 {
+			cfg.VNC.Password = parts[1]
+		}
+		cfg.VNC.User = parts[0]
+	}
+
+	// Process encodings
+	if encodings != "" {
+		cfg.VNC.Encodings = parseEncodings(encodings)
+	}
+
+	// Get URL from remaining args
+	remaining := fs.Args()
+	if len(remaining) > 0 {
+		cfg.URL = remaining[0]
+	}
+
+	// Check for URL in environment
+	if cfg.URL == "" {
+		cfg.URL = os.Getenv("VNC_URL")
+	}
+
+	// Check for cookies in environment
+	if cfg.Connection.Cookie == "" {
+		cfg.Connection.Cookie = os.Getenv("VNC_COOKIES")
+	}
+
+	// Check for password in environment
+	if cfg.VNC.Password == "" {
+		cfg.VNC.Password = os.Getenv("VNC_PASSWORD")
+	}
+
+	return cfg, nil
+}
+
+// parseEncodings parses a comma-separated list of encoding names.
+func parseEncodings(s string) []int32 {
+	names := strings.Split(s, ",")
+	var encodings []int32
+	for _, name := range names {
+		name = strings.TrimSpace(strings.ToLower(name))
+		switch name {
+		case "raw":
+			encodings = append(encodings, 0)
+		case "copyrect":
+			encodings = append(encodings, 1)
+		case "rre":
+			encodings = append(encodings, 2)
+		case "hextile":
+			encodings = append(encodings, 5)
+		case "tight":
+			encodings = append(encodings, 7)
+		case "zrle":
+			encodings = append(encodings, 16)
+		}
+	}
+	return encodings
+}
+
+const usage = `govnc - VNC over WebSocket client and proxy
+
+USAGE:
+    govnc [OPTIONS] <URL>
+
+CONNECTION OPTIONS:
+    -H, --header <Header: Value>    Add custom header (repeatable)
+    -b, --cookie <data|@file>       Send cookies
+    -A, --user-agent <string>       User-Agent header (default: govnc/1.0)
+    -x, --proxy <host:port>         Use proxy (http, socks5)
+    --connect-timeout <seconds>     Connection timeout (default: 30)
+    -k, --insecure                  Skip TLS verification
+
+AUTHENTICATION:
+    -u, --user <user:password>      VNC authentication
+    --auth-none                     Force no authentication
+
+VNC OPTIONS:
+    --shared                        Request shared session (default: true)
+    --exclusive                     Request exclusive session
+    --encoding <list>               Comma-separated encodings (tight,zrle,raw,...)
+
+INPUT OPTIONS:
+    -i, --input <file|->            Read input from file (- for stdin)
+    --type <string>                 Type string and exit
+    --delay <ms>                    Delay between keystrokes
+
+CLIPBOARD OPTIONS:
+    --clip-in <dir>                 Watch directory for outgoing clipboard
+    --clip-out <dir>                Save incoming clipboard to directory
+    --clip-send <text|@file>        Send clipboard text and exit
+
+SERVER MODE:
+    --http <addr:port>              Start HTTP/WS server
+    --proxy-mode <shared|isolated>  Client session mode (default: shared)
+    --max-clients <n>               Max concurrent WebSocket clients
+    --novnc-path <path>             Path to noVNC static files
+    --api-prefix <prefix>           API route prefix (default: /api)
+    --cors-origin <origin>          CORS allowed origin (default: *)
+
+OUTPUT OPTIONS:
+    -v                              Verbose output (use multiple times)
+    -s, --silent                    Silent mode
+    -o, --output <file>             Write output to file
+
+OTHER:
+    -h, --help                      Show help
+    --version                       Show version
+
+ENVIRONMENT VARIABLES:
+    VNC_URL         Default WebSocket URL
+    VNC_COOKIES     Default cookies
+    VNC_PASSWORD    VNC password
+
+EXAMPLES:
+    # Basic interactive connection
+    govnc wss://vnc.example.com/websockify
+
+    # With auth headers
+    govnc -b "session=abc" -H "X-Auth: token" wss://vnc.example.com/ws
+
+    # Type command and exit
+    govnc --type "ls -la\n" wss://vnc.example.com/ws
+
+    # Start proxy server with noVNC web UI
+    govnc --http :8080 wss://vnc.example.com/ws
+    # Then: http://localhost:8080/noVNC/vnc.html
+
+    # Use REST API
+    curl -X PUT localhost:8080/api/keys -d '{"text":"hello\n"}'
+    curl -X PUT localhost:8080/api/clipboard -d '{"text":"copied"}'
+    curl localhost:8080/api/session
+`

@@ -0,0 +1,212 @@
+package input
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/fsnotify/fsnotify"
+)
+
+// ClipboardSender can send clipboard data to a VNC server.
+type ClipboardSender interface {
+	SetClipboard(ctx context.Context, text string) error
+}
+
+// ClipboardHandler is called when clipboard data is received from the server.
+type ClipboardHandler func(text string) error
+
+// ClipboardManager handles clipboard synchronization between local files and VNC.
+type ClipboardManager struct {
+	sender  ClipboardSender
+	handler ClipboardHandler
+
+	watchDir string
+	sentDir  string
+	saveDir  string
+
+	mu            sync.RWMutex
+	lastReceived  string
+	lastRecvTime  time.Time
+	watcher       *fsnotify.Watcher
+}
+
+// ClipboardConfig configures the clipboard manager.
+type ClipboardConfig struct {
+	// WatchDir is the directory to watch for outgoing clipboard files.
+	// Files placed here will be sent to the VNC server.
+	WatchDir string
+
+	// SaveDir is the directory to save incoming clipboard data.
+	// If empty, incoming clipboard is not saved to files.
+	SaveDir string
+
+	// Handler is called when clipboard data is received from the server.
+	Handler ClipboardHandler
+}
+
+// NewClipboardManager creates a new clipboard manager.
+func NewClipboardManager(sender ClipboardSender, cfg *ClipboardConfig) (*ClipboardManager, error) {
+	cm := &ClipboardManager{
+		sender:  sender,
+		handler: cfg.Handler,
+	}
+
+	if cfg.WatchDir != "" {
+		cm.watchDir = cfg.WatchDir
+		cm.sentDir = filepath.Join(cfg.WatchDir, "sent")
+
+		// Create directories
+		if err := os.MkdirAll(cm.watchDir, 0755); err != nil {
+			return nil, fmt.Errorf("creating watch dir: %w", err)
+		}
+		if err := os.MkdirAll(cm.sentDir, 0755); err != nil {
+			return nil, fmt.Errorf("creating sent dir: %w", err)
+		}
+	}
+
+	if cfg.SaveDir != "" {
+		cm.saveDir = cfg.SaveDir
+		if err := os.MkdirAll(cm.saveDir, 0755); err != nil {
+			return nil, fmt.Errorf("creating save dir: %w", err)
+		}
+	}
+
+	return cm, nil
+}
+
+// Start begins watching for clipboard files and processing them.
+func (cm *ClipboardManager) Start(ctx context.Context) error {
+	if cm.watchDir == "" {
+		// No watch directory configured, just wait for context
+		<-ctx.Done()
+		return ctx.Err()
+	}
+
+	watcher, err := fsnotify.NewWatcher()
+	if err != nil {
+		return fmt.Errorf("creating watcher: %w", err)
+	}
+	cm.watcher = watcher
+	defer watcher.Close()
+
+	if err := watcher.Add(cm.watchDir); err != nil {
+		return fmt.Errorf("watching directory: %w", err)
+	}
+
+	slog.Info("watching clipboard directory", slog.String("dir", cm.watchDir))
+
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+
+		case event, ok := <-watcher.Events:
+			if !ok {
+				return nil
+			}
+
+			// Only process Create and Write events
+			if !event.Has(fsnotify.Create) && !event.Has(fsnotify.Write) {
+				continue
+			}
+
+			// Skip the sent/ subdirectory
+			if filepath.Dir(event.Name) != cm.watchDir {
+				continue
+			}
+
+			// Small delay to ensure file is fully written
+			time.Sleep(10 * time.Millisecond)
+
+			cm.processFile(ctx, event.Name)
+
+		case err, ok := <-watcher.Errors:
+			if !ok {
+				return nil
+			}
+			slog.Warn("watcher error", slog.String("error", err.Error()))
+		}
+	}
+}
+
+// processFile reads a file and sends its contents as clipboard data.
+func (cm *ClipboardManager) processFile(ctx context.Context, path string) {
+	info, err := os.Stat(path)
+	if err != nil || info.IsDir() {
+		return
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		slog.Warn("reading clipboard file",
+			slog.String("file", path),
+			slog.String("error", err.Error()))
+		return
+	}
+
+	slog.Info("sending clipboard from file",
+		slog.String("file", filepath.Base(path)),
+		slog.Int("len", len(data)))
+
+	if err := cm.sender.SetClipboard(ctx, string(data)); err != nil {
+		slog.Warn("sending clipboard", slog.String("error", err.Error()))
+		return
+	}
+
+	// Move to sent/ after successful send
+	sentPath := filepath.Join(cm.sentDir, filepath.Base(path))
+	if err := os.Rename(path, sentPath); err != nil {
+		slog.Warn("moving sent file", slog.String("error", err.Error()))
+	}
+}
+
+// Send sends text to the VNC clipboard.
+func (cm *ClipboardManager) Send(ctx context.Context, text string) error {
+	return cm.sender.SetClipboard(ctx, text)
+}
+
+// OnReceive handles incoming clipboard data from the server.
+// This is typically called by the RFB client's clipboard handler.
+func (cm *ClipboardManager) OnReceive(text string) {
+	cm.mu.Lock()
+	cm.lastReceived = text
+	cm.lastRecvTime = time.Now()
+	cm.mu.Unlock()
+
+	// Save to file if configured
+	if cm.saveDir != "" {
+		filename := filepath.Join(cm.saveDir, fmt.Sprintf("%x.clip", time.Now().Unix()))
+		if err := os.WriteFile(filename, []byte(text), 0644); err != nil {
+			slog.Warn("saving clipboard", slog.String("error", err.Error()))
+		} else {
+			slog.Debug("saved clipboard", slog.String("file", filename))
+		}
+	}
+
+	// Call handler if configured
+	if cm.handler != nil {
+		if err := cm.handler(text); err != nil {
+			slog.Warn("clipboard handler error", slog.String("error", err.Error()))
+		}
+	}
+}
+
+// GetLastReceived returns the last received clipboard data and timestamp.
+func (cm *ClipboardManager) GetLastReceived() (string, time.Time) {
+	cm.mu.RLock()
+	defer cm.mu.RUnlock()
+	return cm.lastReceived, cm.lastRecvTime
+}
+
+// Close stops watching and cleans up resources.
+func (cm *ClipboardManager) Close() error {
+	if cm.watcher != nil {
+		return cm.watcher.Close()
+	}
+	return nil
+}

@@ -0,0 +1,205 @@
+// Package input provides input handling utilities for VNC clients.
+package input
+
+import (
+	"context"
+	"io"
+	"time"
+
+	"goVNC/pkg/rfb"
+)
+
+// KeySender can send key events to a VNC server.
+type KeySender interface {
+	KeyEvent(ctx context.Context, key uint32, down bool) error
+}
+
+// Keyboard handles keyboard input processing.
+type Keyboard struct {
+	sender    KeySender
+	delay     time.Duration
+}
+
+// KeyboardOption configures a Keyboard.
+type KeyboardOption func(*Keyboard)
+
+// WithKeyDelay sets a delay between keystrokes.
+func WithKeyDelay(d time.Duration) KeyboardOption {
+	return func(k *Keyboard) {
+		k.delay = d
+	}
+}
+
+// NewKeyboard creates a new keyboard handler.
+func NewKeyboard(sender KeySender, opts ...KeyboardOption) *Keyboard {
+	k := &Keyboard{
+		sender: sender,
+	}
+	for _, opt := range opts {
+		opt(k)
+	}
+	return k
+}
+
+// Press sends a key down event.
+func (k *Keyboard) Press(ctx context.Context, key uint32) error {
+	return k.sender.KeyEvent(ctx, key, true)
+}
+
+// Release sends a key up event.
+func (k *Keyboard) Release(ctx context.Context, key uint32) error {
+	return k.sender.KeyEvent(ctx, key, false)
+}
+
+// Tap presses and releases a key.
+func (k *Keyboard) Tap(ctx context.Context, key uint32) error {
+	if err := k.Press(ctx, key); err != nil {
+		return err
+	}
+	return k.Release(ctx, key)
+}
+
+// Type types a string, converting each character to key events.
+func (k *Keyboard) Type(ctx context.Context, text string) error {
+	for _, r := range text {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		default:
+		}
+
+		key := rfb.RuneToKeysym(r)
+		if err := k.Tap(ctx, key); err != nil {
+			return err
+		}
+
+		if k.delay > 0 {
+			time.Sleep(k.delay)
+		}
+	}
+	return nil
+}
+
+// Combo executes a key combination (e.g., Ctrl+C).
+// All modifier keys are pressed, then the final key is tapped,
+// then all modifiers are released in reverse order.
+func (k *Keyboard) Combo(ctx context.Context, keys ...uint32) error {
+	if len(keys) == 0 {
+		return nil
+	}
+
+	// Press all but last key
+	modifiers := keys[:len(keys)-1]
+	finalKey := keys[len(keys)-1]
+
+	// Press modifiers
+	for _, mod := range modifiers {
+		if err := k.Press(ctx, mod); err != nil {
+			return err
+		}
+	}
+
+	// Tap final key
+	if err := k.Tap(ctx, finalKey); err != nil {
+		return err
+	}
+
+	// Release modifiers in reverse order
+	for i := len(modifiers) - 1; i >= 0; i-- {
+		if err := k.Release(ctx, modifiers[i]); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// Writer returns an io.Writer that types input to the VNC session.
+func (k *Keyboard) Writer(ctx context.Context) io.Writer {
+	return &keyboardWriter{
+		ctx:      ctx,
+		keyboard: k,
+	}
+}
+
+type keyboardWriter struct {
+	ctx      context.Context
+	keyboard *Keyboard
+}
+
+func (w *keyboardWriter) Write(p []byte) (int, error) {
+	err := w.keyboard.Type(w.ctx, string(p))
+	if err != nil {
+		return 0, err
+	}
+	return len(p), nil
+}
+
+// ParseKeyName converts a key name to a keysym.
+// Supports names like "ctrl", "shift", "alt", "return", "tab", etc.
+func ParseKeyName(name string) (uint32, bool) {
+	switch name {
+	case "ctrl", "control":
+		return rfb.KeyControlL, true
+	case "shift":
+		return rfb.KeyShiftL, true
+	case "alt":
+		return rfb.KeyAltL, true
+	case "meta", "super", "win", "cmd":
+		return rfb.KeySuperL, true
+	case "return", "enter":
+		return rfb.KeyReturn, true
+	case "tab":
+		return rfb.KeyTab, true
+	case "escape", "esc":
+		return rfb.KeyEscape, true
+	case "backspace":
+		return rfb.KeyBackspace, true
+	case "delete", "del":
+		return rfb.KeyDelete, true
+	case "insert", "ins":
+		return rfb.KeyInsert, true
+	case "home":
+		return rfb.KeyHome, true
+	case "end":
+		return rfb.KeyEnd, true
+	case "pageup", "pgup":
+		return rfb.KeyPageUp, true
+	case "pagedown", "pgdn":
+		return rfb.KeyPageDown, true
+	case "left":
+		return rfb.KeyLeft, true
+	case "right":
+		return rfb.KeyRight, true
+	case "up":
+		return rfb.KeyUp, true
+	case "down":
+		return rfb.KeyDown, true
+	case "f1":
+		return rfb.KeyF1, true
+	case "f2":
+		return rfb.KeyF2, true
+	case "f3":
+		return rfb.KeyF3, true
+	case "f4":
+		return rfb.KeyF4, true
+	case "f5":
+		return rfb.KeyF5, true
+	case "f6":
+		return rfb.KeyF6, true
+	case "f7":
+		return rfb.KeyF7, true
+	case "f8":
+		return rfb.KeyF8, true
+	case "f9":
+		return rfb.KeyF9, true
+	case "f10":
+		return rfb.KeyF10, true
+	case "f11":
+		return rfb.KeyF11, true
+	case "f12":
+		return rfb.KeyF12, true
+	default:
+		return 0, false
+	}
+}

@@ -0,0 +1,228 @@
+// Package proxy provides VNC proxy functionality for multiplexing clients.
+package proxy
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+
+	"goVNC/pkg/rfb"
+	"goVNC/pkg/transport"
+)
+
+// SessionMode determines how clients interact with the VNC session.
+type SessionMode int
+
+const (
+	// SharedMode - all clients share the same VNC session view and can send input.
+	SharedMode SessionMode = iota
+
+	// IsolatedMode - input is queued and processed sequentially.
+	IsolatedMode
+)
+
+// Multiplexer manages multiple WebSocket clients connected to a single VNC session.
+type Multiplexer struct {
+	vnc      *rfb.Client
+	mode     SessionMode
+
+	clients  map[string]*ClientConn
+	clientMu sync.RWMutex
+
+	// For broadcasting server messages to all clients
+	broadcast chan []byte
+
+	closed bool
+	closeMu sync.RWMutex
+}
+
+// ClientConn represents a connected client.
+type ClientConn struct {
+	ID        string
+	Transport transport.Transport
+	send      chan []byte
+	done      chan struct{}
+}
+
+// NewMultiplexer creates a new multiplexer for the given VNC client.
+func NewMultiplexer(vnc *rfb.Client, mode SessionMode) *Multiplexer {
+	return &Multiplexer{
+		vnc:       vnc,
+		mode:      mode,
+		clients:   make(map[string]*ClientConn),
+		broadcast: make(chan []byte, 100),
+	}
+}
+
+// AddClient registers a new client connection.
+func (m *Multiplexer) AddClient(id string, t transport.Transport) *ClientConn {
+	client := &ClientConn{
+		ID:        id,
+		Transport: t,
+		send:      make(chan []byte, 100),
+		done:      make(chan struct{}),
+	}
+
+	m.clientMu.Lock()
+	m.clients[id] = client
+	m.clientMu.Unlock()
+
+	slog.Info("client connected", slog.String("id", id))
+	return client
+}
+
+// RemoveClient unregisters a client.
+func (m *Multiplexer) RemoveClient(id string) {
+	m.clientMu.Lock()
+	client, ok := m.clients[id]
+	if ok {
+		delete(m.clients, id)
+		close(client.done)
+	}
+	m.clientMu.Unlock()
+
+	if ok {
+		slog.Info("client disconnected", slog.String("id", id))
+	}
+}
+
+// GetClient returns a client by ID.
+func (m *Multiplexer) GetClient(id string) (*ClientConn, bool) {
+	m.clientMu.RLock()
+	defer m.clientMu.RUnlock()
+	client, ok := m.clients[id]
+	return client, ok
+}
+
+// ClientCount returns the number of connected clients.
+func (m *Multiplexer) ClientCount() int {
+	m.clientMu.RLock()
+	defer m.clientMu.RUnlock()
+	return len(m.clients)
+}
+
+// Broadcast sends a message to all connected clients.
+func (m *Multiplexer) Broadcast(data []byte) {
+	m.clientMu.RLock()
+	defer m.clientMu.RUnlock()
+
+	for _, client := range m.clients {
+		select {
+		case client.send <- data:
+		default:
+			slog.Warn("client send buffer full", slog.String("id", client.ID))
+		}
+	}
+}
+
+// HandleClientInput processes input from a client and forwards to VNC.
+func (m *Multiplexer) HandleClientInput(ctx context.Context, clientID string, data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+
+	// Parse the message type
+	msgType := data[0]
+
+	switch msgType {
+	case rfb.MsgTypeKeyEvent:
+		// Forward key events to VNC
+		return m.vnc.Transport().Write(ctx, data)
+
+	case rfb.MsgTypePointerEvent:
+		// Forward pointer events to VNC
+		return m.vnc.Transport().Write(ctx, data)
+
+	case rfb.MsgTypeClientCutText:
+		// Forward clipboard to VNC
+		return m.vnc.Transport().Write(ctx, data)
+
+	case rfb.MsgTypeFramebufferUpdateRequest:
+		// Don't forward FBU requests - the main client handles these
+		return nil
+
+	case rfb.MsgTypeSetEncodings:
+		// Don't forward encoding changes
+		return nil
+
+	case rfb.MsgTypeSetPixelFormat:
+		// Don't forward pixel format changes
+		return nil
+
+	default:
+		slog.Debug("unknown client message type",
+			slog.String("client", clientID),
+			slog.Int("type", int(msgType)))
+	}
+
+	return nil
+}
+
+// RunClientWriter writes messages from the send channel to a client.
+func (m *Multiplexer) RunClientWriter(ctx context.Context, client *ClientConn) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-client.done:
+			return nil
+		case data := <-client.send:
+			if err := client.Transport.Write(ctx, data); err != nil {
+				return fmt.Errorf("writing to client: %w", err)
+			}
+		}
+	}
+}
+
+// RunClientReader reads messages from a client and processes them.
+func (m *Multiplexer) RunClientReader(ctx context.Context, client *ClientConn) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-client.done:
+			return nil
+		default:
+		}
+
+		data, err := client.Transport.Read(ctx)
+		if err != nil {
+			return fmt.Errorf("reading from client: %w", err)
+		}
+
+		if err := m.HandleClientInput(ctx, client.ID, data); err != nil {
+			slog.Warn("handling client input",
+				slog.String("client", client.ID),
+				slog.String("error", err.Error()))
+		}
+	}
+}
+
+// Close shuts down the multiplexer.
+func (m *Multiplexer) Close() error {
+	m.closeMu.Lock()
+	defer m.closeMu.Unlock()
+
+	if m.closed {
+		return nil
+	}
+	m.closed = true
+
+	// Close all client connections
+	m.clientMu.Lock()
+	for id, client := range m.clients {
+		close(client.done)
+		client.Transport.Close()
+		delete(m.clients, id)
+	}
+	m.clientMu.Unlock()
+
+	close(m.broadcast)
+	return nil
+}
+
+// VNCClient returns the underlying VNC client.
+func (m *Multiplexer) VNCClient() *rfb.Client {
+	return m.vnc
+}

@@ -0,0 +1,278 @@
+package rfb
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+
+	"goVNC/pkg/transport"
+)
+
+// MessageHandler is called when a server message is received.
+type MessageHandler func(msg *ServerMessage)
+
+// ClipboardHandler is called when clipboard data is received from the server.
+type ClipboardHandler func(text string)
+
+// Client is an RFB protocol client.
+type Client struct {
+	transport transport.Transport
+	session   *Session
+	config    *ClientConfig
+
+	// Message handlers
+	onMessage   MessageHandler
+	onClipboard ClipboardHandler
+
+	// Synchronization
+	mu       sync.RWMutex
+	closed   bool
+
+	// Last received clipboard (for API access)
+	lastClipboard     string
+	lastClipboardTime time.Time
+	clipMu            sync.RWMutex
+}
+
+// ClientConfig configures the RFB client.
+type ClientConfig struct {
+	// Handshake configuration
+	Handshake *HandshakeConfig
+
+	// Encodings to request from the server.
+	Encodings []int32
+
+	// ReadLimit is the maximum message size (default 64MB).
+	ReadLimit int64
+
+	// KeyTimeout is the timeout for key events (default 1s).
+	KeyTimeout time.Duration
+}
+
+// DefaultClientConfig returns default client configuration.
+func DefaultClientConfig() *ClientConfig {
+	return &ClientConfig{
+		Handshake:  DefaultHandshakeConfig(),
+		Encodings:  DefaultEncodings(),
+		ReadLimit:  64 * 1024 * 1024, // 64MB
+		KeyTimeout: 1 * time.Second,
+	}
+}
+
+// NewClient creates a new RFB client with the given transport.
+func NewClient(t transport.Transport, cfg *ClientConfig) *Client {
+	if cfg == nil {
+		cfg = DefaultClientConfig()
+	}
+	return &Client{
+		transport: t,
+		config:    cfg,
+	}
+}
+
+// Connect performs the RFB handshake and initializes the session.
+func (c *Client) Connect(ctx context.Context) (*Session, error) {
+	c.mu.Lock()
+	if c.closed {
+		c.mu.Unlock()
+		return nil, fmt.Errorf("client is closed")
+	}
+
+	// Perform handshake
+	session, err := Handshake(ctx, c.transport, c.config.Handshake)
+	if err != nil {
+		c.mu.Unlock()
+		return nil, fmt.Errorf("handshake failed: %w", err)
+	}
+	c.session = session
+
+	// Set read limit
+	c.transport.SetReadLimit(c.config.ReadLimit)
+
+	// Send encodings
+	if len(c.config.Encodings) > 0 {
+		msg := EncodeSetEncodings(c.config.Encodings)
+		if err := c.transport.Write(ctx, msg); err != nil {
+			c.mu.Unlock()
+			return nil, fmt.Errorf("sending encodings: %w", err)
+		}
+	}
+
+	// Release lock before calling RequestFramebuffer (which also takes the lock)
+	c.mu.Unlock()
+
+	// Request initial framebuffer
+	if err := c.RequestFramebuffer(ctx, false); err != nil {
+		return nil, fmt.Errorf("requesting initial framebuffer: %w", err)
+	}
+
+	return session, nil
+}
+
+// Session returns the current session info.
+func (c *Client) Session() *Session {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.session
+}
+
+// OnMessage sets the handler for all server messages.
+func (c *Client) OnMessage(handler MessageHandler) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.onMessage = handler
+}
+
+// OnClipboard sets the handler for clipboard messages.
+func (c *Client) OnClipboard(handler ClipboardHandler) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.onClipboard = handler
+}
+
+// Listen reads and processes server messages until the context is cancelled.
+func (c *Client) Listen(ctx context.Context) error {
+	for {
+		data, err := c.transport.Read(ctx)
+		if err != nil {
+			return fmt.Errorf("reading message: %w", err)
+		}
+
+		if len(data) == 0 {
+			slog.Warn("received empty message")
+			continue
+		}
+
+		msg, err := ParseServerMessage(data)
+		if err != nil {
+			slog.Warn("parsing message", slog.String("error", err.Error()))
+			continue
+		}
+
+		// Call message handler
+		c.mu.RLock()
+		onMessage := c.onMessage
+		onClipboard := c.onClipboard
+		c.mu.RUnlock()
+
+		if onMessage != nil {
+			onMessage(msg)
+		}
+
+		// Handle specific message types
+		switch msg.Type {
+		case MsgTypeFramebufferUpdate:
+			// Request next incremental update
+			if err := c.RequestFramebuffer(ctx, true); err != nil {
+				return fmt.Errorf("requesting framebuffer: %w", err)
+			}
+
+		case MsgTypeServerCutText:
+			cut, err := ParseServerCutText(data)
+			if err != nil {
+				slog.Warn("parsing clipboard", slog.String("error", err.Error()))
+				continue
+			}
+			// Store for API access
+			c.clipMu.Lock()
+			c.lastClipboard = cut.Text
+			c.lastClipboardTime = time.Now()
+			c.clipMu.Unlock()
+
+			if onClipboard != nil {
+				onClipboard(cut.Text)
+			}
+
+		case MsgTypeBell:
+			slog.Info("bell received")
+		}
+	}
+}
+
+// RequestFramebuffer sends a framebuffer update request.
+func (c *Client) RequestFramebuffer(ctx context.Context, incremental bool) error {
+	c.mu.RLock()
+	session := c.session
+	c.mu.RUnlock()
+
+	if session == nil {
+		return fmt.Errorf("not connected")
+	}
+
+	msg := EncodeFramebufferUpdateRequest(incremental, 0, 0, session.Width, session.Height)
+	return c.transport.Write(ctx, msg)
+}
+
+// KeyEvent sends a key press or release event.
+func (c *Client) KeyEvent(ctx context.Context, key uint32, down bool) error {
+	ctx, cancel := context.WithTimeout(ctx, c.config.KeyTimeout)
+	defer cancel()
+
+	msg := EncodeKeyEvent(down, key)
+	return c.transport.Write(ctx, msg)
+}
+
+// Tap sends a key press followed by release.
+func (c *Client) Tap(ctx context.Context, key uint32) error {
+	if err := c.KeyEvent(ctx, key, true); err != nil {
+		return err
+	}
+	return c.KeyEvent(ctx, key, false)
+}
+
+// Type sends a string as key events.
+func (c *Client) Type(ctx context.Context, text string) error {
+	for _, r := range text {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		default:
+		}
+
+		key := RuneToKeysym(r)
+		if err := c.Tap(ctx, key); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// PointerEvent sends a mouse/pointer event.
+func (c *Client) PointerEvent(ctx context.Context, buttonMask uint8, x, y uint16) error {
+	msg := EncodePointerEvent(buttonMask, x, y)
+	return c.transport.Write(ctx, msg)
+}
+
+// SetClipboard sends clipboard text to the server.
+func (c *Client) SetClipboard(ctx context.Context, text string) error {
+	msg := EncodeClientCutText(text)
+	return c.transport.Write(ctx, msg)
+}
+
+// GetLastClipboard returns the last received clipboard data.
+func (c *Client) GetLastClipboard() (string, time.Time) {
+	c.clipMu.RLock()
+	defer c.clipMu.RUnlock()
+	return c.lastClipboard, c.lastClipboardTime
+}
+
+// Close closes the client and transport.
+func (c *Client) Close() error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.closed {
+		return nil
+	}
+	c.closed = true
+
+	return c.transport.Close()
+}
+
+// Transport returns the underlying transport.
+// This is useful for advanced operations or passing to the proxy.
+func (c *Client) Transport() transport.Transport {
+	return c.transport
+}

@@ -0,0 +1,237 @@
+package rfb
+
+import (
+	"context"
+	"crypto/des"
+	"fmt"
+	"strings"
+
+	"goVNC/pkg/transport"
+)
+
+const (
+	// RFBVersion is the RFB protocol version we support.
+	RFBVersion = "RFB 003.008\n"
+)
+
+// SecurityType represents an RFB security type.
+type SecurityType uint8
+
+const (
+	SecurityTypeInvalid   SecurityType = 0
+	SecurityTypeNone      SecurityType = 1
+	SecurityTypeVNCAuth   SecurityType = 2
+	SecurityTypeTight     SecurityType = 16
+	SecurityTypeVeNCrypt  SecurityType = 19
+)
+
+// HandshakeConfig configures the RFB handshake.
+type HandshakeConfig struct {
+	// SharedSession requests a shared session if true.
+	SharedSession bool
+
+	// Password for VNC authentication (SecurityTypeVNCAuth).
+	Password string
+
+	// AllowedSecurityTypes lists allowed security types.
+	// If empty, only SecurityTypeNone is allowed.
+	AllowedSecurityTypes []SecurityType
+}
+
+// DefaultHandshakeConfig returns default handshake configuration.
+func DefaultHandshakeConfig() *HandshakeConfig {
+	return &HandshakeConfig{
+		SharedSession:        true,
+		AllowedSecurityTypes: []SecurityType{SecurityTypeNone},
+	}
+}
+
+// Handshake performs the RFB protocol handshake and returns a Session.
+func Handshake(ctx context.Context, t transport.Transport, cfg *HandshakeConfig) (*Session, error) {
+	if cfg == nil {
+		cfg = DefaultHandshakeConfig()
+	}
+
+	// Step 1: Read server version
+	serverVersionData, err := t.Read(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("reading server version: %w", err)
+	}
+	serverVersion := strings.TrimSpace(string(serverVersionData))
+
+	// Step 2: Send client version
+	err = t.Write(ctx, []byte(RFBVersion))
+	if err != nil {
+		return nil, fmt.Errorf("sending client version: %w", err)
+	}
+
+	// Step 3: Read security types
+	secTypes, err := t.Read(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("reading security types: %w", err)
+	}
+
+	if len(secTypes) < 1 {
+		return nil, fmt.Errorf("empty security types message")
+	}
+
+	// Parse security types
+	numSecTypes := int(secTypes[0])
+	if numSecTypes == 0 {
+		// Version 3.3 error or failure
+		if len(secTypes) >= 5 {
+			errLen := int(secTypes[1])<<24 | int(secTypes[2])<<16 | int(secTypes[3])<<8 | int(secTypes[4])
+			if len(secTypes) >= 5+errLen {
+				return nil, fmt.Errorf("server rejected: %s", string(secTypes[5:5+errLen]))
+			}
+		}
+		return nil, fmt.Errorf("server rejected connection")
+	}
+
+	if len(secTypes) < 1+numSecTypes {
+		return nil, fmt.Errorf("security types message too short")
+	}
+
+	// Find a supported security type
+	var selectedSecurity SecurityType
+	for i := 0; i < numSecTypes; i++ {
+		offered := SecurityType(secTypes[1+i])
+		for _, allowed := range cfg.AllowedSecurityTypes {
+			if offered == allowed {
+				selectedSecurity = offered
+				break
+			}
+		}
+		if selectedSecurity != 0 {
+			break
+		}
+	}
+
+	if selectedSecurity == 0 {
+		return nil, fmt.Errorf("no supported security type (server offered: %v)", secTypes[1:1+numSecTypes])
+	}
+
+	// Step 4: Send security choice
+	err = t.Write(ctx, []byte{byte(selectedSecurity)})
+	if err != nil {
+		return nil, fmt.Errorf("sending security choice: %w", err)
+	}
+
+	// Step 5: Handle security type specific authentication
+	switch selectedSecurity {
+	case SecurityTypeNone:
+		// No authentication required
+	case SecurityTypeVNCAuth:
+		err = handleVNCAuth(ctx, t, cfg.Password)
+		if err != nil {
+			return nil, fmt.Errorf("VNC authentication: %w", err)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported security type: %d", selectedSecurity)
+	}
+
+	// Step 6: Read security result
+	secResult, err := t.Read(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("reading security result: %w", err)
+	}
+
+	if len(secResult) < 4 {
+		// Some servers don't send security result for None auth in older versions
+		if selectedSecurity != SecurityTypeNone {
+			return nil, fmt.Errorf("security result too short: %d bytes", len(secResult))
+		}
+		// Treat as success for None auth
+	} else {
+		result := uint32(secResult[0])<<24 | uint32(secResult[1])<<16 | uint32(secResult[2])<<8 | uint32(secResult[3])
+		if result != 0 {
+			return nil, fmt.Errorf("security handshake failed: result=%d", result)
+		}
+	}
+
+	// Step 7: Send ClientInit
+	clientInit := byte(0)
+	if cfg.SharedSession {
+		clientInit = 1
+	}
+	err = t.Write(ctx, []byte{clientInit})
+	if err != nil {
+		return nil, fmt.Errorf("sending client init: %w", err)
+	}
+
+	// Step 8: Read ServerInit
+	serverInit, err := t.Read(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("reading server init: %w", err)
+	}
+
+	session, err := ParseServerInit(serverInit)
+	if err != nil {
+		return nil, fmt.Errorf("parsing server init: %w", err)
+	}
+	session.ServerVersion = serverVersion
+
+	return session, nil
+}
+
+// handleVNCAuth handles VNC authentication (DES challenge-response).
+func handleVNCAuth(ctx context.Context, t transport.Transport, password string) error {
+	// Read 16-byte challenge
+	challenge, err := t.Read(ctx)
+	if err != nil {
+		return fmt.Errorf("reading challenge: %w", err)
+	}
+	if len(challenge) != 16 {
+		return fmt.Errorf("unexpected challenge length: %d", len(challenge))
+	}
+
+	// Encrypt challenge with password using DES
+	response := vncAuthEncrypt(challenge, password)
+
+	// Send 16-byte response
+	err = t.Write(ctx, response)
+	if err != nil {
+		return fmt.Errorf("sending response: %w", err)
+	}
+
+	return nil
+}
+
+// vncAuthEncrypt encrypts the VNC authentication challenge.
+// VNC uses a weird DES variant where key bits are reversed.
+func vncAuthEncrypt(challenge []byte, password string) []byte {
+	// Pad or truncate password to 8 bytes
+	key := make([]byte, 8)
+	copy(key, password)
+
+	// Reverse bits in each byte of the key (VNC quirk)
+	for i := range key {
+		key[i] = reverseBits(key[i])
+	}
+
+	// Create DES cipher
+	cipher, err := des.NewCipher(key)
+	if err != nil {
+		// Should not happen with 8-byte key
+		return challenge
+	}
+
+	// Encrypt with DES in ECB mode (2 blocks of 8 bytes)
+	response := make([]byte, 16)
+	cipher.Encrypt(response[0:8], challenge[0:8])
+	cipher.Encrypt(response[8:16], challenge[8:16])
+
+	return response
+}
+
+// reverseBits reverses the bits in a byte.
+// VNC authentication requires this quirk for the DES key.
+func reverseBits(b byte) byte {
+	var result byte
+	for i := 0; i < 8; i++ {
+		if b&(1<<i) != 0 {
+			result |= 1 << (7 - i)
+		}
+	}
+	return result
+}