@ebowwa/terminal 0.2.1 → 0.3.1

package/dist/api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * API routes for Multi-Node Tmux Session Manager
+ * Provides REST API for managing tmux sessions across multiple VPS nodes
+ */
+import { Hono } from "hono";
+declare const tmuxApi: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export { tmuxApi };

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Core SSH client for executing commands on remote servers
+ * Uses persistent connection pool for efficient reuse
+ * Uses base64 encoding to avoid shell escaping issues
+ */
+import type { SSHOptions } from "./types.js";
+/**
+ * Execute a command on a remote server via SSH
+ * Uses persistent connection pool for better performance
+ * @param command - Shell command to execute
+ * @param options - SSH connection options
+ * @returns Command output as string
+ */
+export declare function execSSH(command: string, options: SSHOptions): Promise<string>;

package/dist/config.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SSH Config Manager
+ *
+ * Manages ~/.ssh/config entries for easy node access.
+ * When a node is created, adds an alias so you can:
+ *   ssh node-<id>    or    ssh <name>
+ * Instead of:
+ *   ssh -i ~/.../key -o StrictHostKeyChecking=no root@167.235.236.8
+ */
+export interface SSHConfigEntry {
+    id: string;
+    name: string;
+    host: string;
+    user?: string;
+    keyPath: string;
+    port?: number;
+}
+/**
+ * Add or update an SSH config entry for a node
+ */
+export declare function addSSHConfigEntry(entry: SSHConfigEntry): void;
+/**
+ * Remove an SSH config entry for a node
+ */
+export declare function removeSSHConfigEntry(id: string): void;
+/**
+ * Update IP address for an existing node (e.g., after rebuild)
+ */
+export declare function updateSSHConfigHost(id: string, newHost: string): void;
+/**
+ * List all managed SSH config entries
+ */
+export declare function listSSHConfigEntries(): SSHConfigEntry[];
+/**
+ * Validate SSH connection works with the configured key
+ * Returns true if connection succeeds, throws on failure with diagnostic info
+ */
+export declare function validateSSHConnection(host: string, keyPath: string, user?: string, timeoutSeconds?: number): Promise<{
+    success: boolean;
+    error?: string;
+    diagnostics?: string;
+}>;
+/**
+ * Ensure SSH key is loaded correctly and agent doesn't interfere
+ * Clears wrong keys from agent and adds the correct one
+ */
+export declare function ensureCorrectSSHKey(keyPath: string): Promise<void>;
+/**
+ * Wait for SSH to become ready on a new server
+ * Polls until connection succeeds or timeout
+ */
+export declare function waitForSSHReady(host: string, keyPath: string, options?: {
+    user?: string;
+    maxAttempts?: number;
+    intervalMs?: number;
+    onAttempt?: (attempt: number, maxAttempts: number) => void;
+}): Promise<{
+    success: boolean;
+    attempts: number;
+    error?: string;
+}>;
+/**
+ * Sync result for a single node
+ */
+export interface SyncResult {
+    id: string;
+    name: string;
+    ip: string;
+    status: "added" | "updated" | "skipped" | "error";
+    error?: string;
+    sshReady?: boolean;
+}
+/**
+ * Sync all existing Hetzner nodes to SSH config
+ * Call this to add aliases for nodes created before this feature
+ */
+export declare function syncNodesToSSHConfig(nodes: Array<{
+    id: string;
+    name: string;
+    ip: string;
+    keyPath: string;
+}>, options?: {
+    validateSSH?: boolean;
+    onProgress?: (result: SyncResult) => void;
+}): Promise<SyncResult[]>;

package/dist/error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SSH error class
+ */
+export declare class SSHError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/exec.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SSH command execution functions
+ */
+import type { SSHOptions } from "./types.js";
+/**
+ * Execute multiple SSH commands in parallel using multiple connections
+ *
+ * DESIGN DECISION: Multiple Connections vs Single Connection
+ * ===========================================================
+ *
+ * We use MULTIPLE SSH connections to avoid channel saturation issues.
+ * SSH servers typically limit concurrent channels per connection (~10).
+ * When executing 9+ commands in parallel, we can exceed this limit.
+ *
+ * Solution: Distribute commands across multiple pooled connections.
+ * Each connection handles a subset of commands, staying within channel limits.
+ *
+ * DESIGN DECISION: Promise.allSettled() vs Promise.all()
+ * ======================================================
+ *
+ * We use Promise.allSettled() instead of Promise.all() for a critical reason:
+ * Resource monitoring should be RESILIENT. If one command fails (e.g., GPU
+ * query on a CPU-only server), we still want results from all other commands.
+ *
+ * Example scenario:
+ * - CPU, memory, disk commands: succeed
+ * - GPU command: fails (no NVIDIA GPU)
+ * - Network command: succeeds
+ *
+ * With Promise.all(): entire batch fails, no metrics collected
+ * With Promise.allSettled(): we get 6/7 metrics, GPU returns "0" fallback
+ *
+ * ERROR HANDLING:
+ * ==============
+ * 1. Individual command failures are logged to console
+ * 2. Failed commands return "0" as fallback (matches execSSH default)
+ * 3. The function always completes successfully (never throws)
+ * 4. Calling code can check for "0" values to detect failures
+ */
+export declare function execSSHParallel(commands: Record<string, string>, options: SSHOptions): Promise<Record<string, string>>;
+/**
+ * Test SSH connection to a remote server
+ * @param options - SSH connection options
+ * @returns True if connection successful
+ */
+export declare function testSSHConnection(options: SSHOptions): Promise<boolean>;

package/dist/files.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Remote file operations via SSH
+ */
+import type { SSHOptions } from "./types.js";
+import { SSHError } from "./error.js";
+/**
+ * Path sanitization options
+ */
+export interface SanitizePathOptions {
+    /**
+     * Allowed base directories (absolute paths)
+     * Default: ["/root"] for root user
+     */
+    allowedBaseDirs?: string[];
+    /**
+     * User context for determining default base directory
+     */
+    user?: string;
+    /**
+     * Whether to allow absolute paths
+     * Default: false (security best practice)
+     */
+    allowAbsolutePaths?: boolean;
+    /**
+     * Maximum path depth to prevent deep traversal attempts
+     * Default: 20
+     */
+    maxDepth?: number;
+    /**
+     * Log suspicious path attempts
+     * Default: true
+     */
+    logSuspicious?: boolean;
+}
+/**
+ * Path traversal security error
+ */
+export declare class PathTraversalError extends SSHError {
+    readonly attemptedPath: string;
+    readonly reason: string;
+    constructor(message: string, attemptedPath: string, reason: string);
+}
+/**
+ * Security event log for path traversal attempts
+ */
+interface SecurityEvent {
+    timestamp: string;
+    attemptedPath: string;
+    reason: string;
+    severity: "blocked" | "suspicious" | "warning";
+}
+/**
+ * Get recent security events for monitoring
+ */
+export declare function getSecurityEvents(limit?: number): SecurityEvent[];
+/**
+ * Clear old security events (for maintenance)
+ */
+export declare function clearSecurityEvents(olderThanMs?: number): number;
+/**
+ * Sanitize and validate a file path for security
+ *
+ * This function prevents path traversal attacks by:
+ * 1. Rejecting paths with .. components
+ * 2. Validating against allowed base directories
+ * 3. Normalizing paths to remove . and redundant /
+ * 4. Checking for null bytes and other escape sequences
+ * 5. Limiting path depth to prevent deep traversal
+ *
+ * @param inputPath - The user-provided path to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized absolute path
+ * @throws PathTraversalError if path is suspicious or invalid
+ *
+ * @example
+ * ```ts
+ * // Safe: within /root
+ * sanitizePath("project/file.txt", { user: "root" })
+ * // Returns: "/root/project/file.txt"
+ *
+ * // BLOCKED: attempts to escape
+ * sanitizePath("../../../etc/passwd", { user: "root" })
+ * // Throws: PathTraversalError
+ *
+ * // BLOCKED: null byte injection
+ * sanitizePath("file.txt\0../../../etc/passwd", { user: "root" })
+ * // Throws: PathTraversalError
+ * ```
+ */
+export declare function sanitizePath(inputPath: string, options?: SanitizePathOptions): string;
+export type FileType = "file" | "directory";
+export interface RemoteFile {
+    name: string;
+    path: string;
+    size: string;
+    modified: string;
+    type: FileType;
+}
+export type PreviewType = "text" | "image" | "binary" | "error";
+export interface FilePreview {
+    type: PreviewType;
+    content?: string;
+    error?: string;
+}
+/**
+ * List files in a directory on remote server
+ * @param path - Directory path to list (default: .)
+ * @param options - SSH connection options
+ * @returns List of files with metadata
+ * @throws PathTraversalError if path attempts to escape allowed directories
+ * @throws SSHError if SSH command fails
+ */
+export declare function listFiles(path: string, options: SSHOptions): Promise<RemoteFile[]>;
+/**
+ * Preview a file's content from remote server
+ * @param filePath - Path to the file to preview
+ * @param options - SSH connection options
+ * @returns File content for preview
+ * @throws PathTraversalError if path attempts to escape allowed directories
+ * @throws SSHError if SSH command fails
+ */
+export declare function previewFile(filePath: string, options: SSHOptions): Promise<FilePreview>;
+export {};

package/dist/fingerprint.d.ts

@@ -0,0 +1,66 @@
+/**
+ * SSH fingerprint utilities with validation and recovery
+ */
+import type { SSHOptions } from "./types.js";
+/**
+ * Get SSH fingerprint from remote server
+ * @param options - SSH connection options
+ * @returns SSH fingerprint or null
+ */
+export declare function getSSHFingerprint(options: SSHOptions): Promise<string | null>;
+/**
+ * Get SSH fingerprint from a local private key file
+ * @param keyPath - Path to the private key file
+ * @returns SSH fingerprint (SHA256 format) or null
+ */
+export declare function getLocalKeyFingerprint(keyPath: string): Promise<string | null>;
+/**
+ * Convert MD5 fingerprint format to SHA256 format (for comparison)
+ * Hetzner returns MD5 like "29:cd:c1:c3:84:eb:ca:31:a4:1f:94:69:0c:84:b3:56"
+ * We need to handle both formats
+ */
+export declare function normalizeFingerprint(fingerprint: string): string;
+/**
+ * Validate that a local SSH key matches what's on a remote server
+ * @param host - Server hostname or IP
+ * @param keyPath - Path to local private key
+ * @returns Validation result
+ */
+export declare function validateSSHKeyMatch(host: string, keyPath: string): Promise<{
+    valid: boolean;
+    localFingerprint?: string;
+    remoteFingerprint?: string;
+    error?: string;
+}>;
+/**
+ * Check if we can SSH to a server with a given key
+ * @param host - Server hostname or IP
+ * @param keyPath - Path to SSH private key
+ * @returns true if SSH works
+ */
+export declare function testSSHKeyConnection(host: string, keyPath: string): Promise<boolean>;
+/**
+ * SSH Key Mismatch Error with recovery suggestions
+ */
+export declare class SSHKeyMismatchError extends Error {
+    host: string;
+    localFingerprint: string;
+    hetznerFingerprint: string;
+    keyPath: string;
+    constructor(host: string, localFingerprint: string, hetznerFingerprint: string, keyPath: string);
+}
+/**
+ * Comprehensive SSH key validation for server creation
+ * @param host - Server hostname or IP
+ * @param keyPath - Path to local SSH key
+ * @param hetznerKeyId - SSH key ID on Hetzner (for comparison)
+ * @returns Validation result with recovery suggestions
+ */
+export declare function validateSSHKeyForServer(host: string, keyPath: string, hetznerKeyId?: string): Promise<{
+    canConnect: boolean;
+    fingerprintMatch: boolean;
+    localFingerprint?: string;
+    remoteFingerprint?: string;
+    error?: string;
+    recovery?: string[];
+}>;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SSH utility library - modular entry point
+ */
+export { TmuxSessionManager, getTmuxManager, resetTmuxManager, type Node, type TmuxSession, type DetailedTmuxSession, type BatchOperationResult, type CreateSessionOptions, type BatchCommandOptions, type SessionQueryOptions, } from "./tmux-manager.js";
+export type { SSHOptions, SCPOptions } from "./types.js";
+export { SSHError } from "./error.js";
+export { execSSH } from "./client.js";
+export { execSSHParallel, testSSHConnection } from "./exec.js";
+export { execViaTmux, execViaTmuxParallel } from "./tmux-exec.js";
+export { scpUpload, scpDownload } from "./scp.js";
+export { listFiles, previewFile, sanitizePath, PathTraversalError, getSecurityEvents, clearSecurityEvents, type FileType, type RemoteFile, type PreviewType, type FilePreview, type SanitizePathOptions, } from "./files.js";
+export { getSSHFingerprint, getLocalKeyFingerprint, normalizeFingerprint, validateSSHKeyMatch, testSSHKeyConnection, validateSSHKeyForServer, SSHKeyMismatchError } from "./fingerprint.js";
+export { createPTYSession, writeToPTY, setPTYSize, readFromPTY, closePTYSession, getPTYSession, getActivePTYSessions, } from "./pty.js";
+export { getSSHPool, closeGlobalSSHPool, getActiveSSHConnections, SSHConnectionPool, } from "./pool.js";
+export { closeSession, cleanupStaleSessions, getOrCreateSession, getSession, getAllSessions, getAllSessionInfo, getSessionInfo, getSessionCount, getSessionsByHost, attachWebSocket, writeToSession, resizeSession, detachWebSocket, } from "./sessions.js";
+export type { TerminalSession, SessionInfo } from "./sessions.js";
+export { generateSessionName, isTmuxInstalled, installTmux, ensureTmux, listTmuxSessions, hasTmuxSession, createOrAttachTmuxSession, killTmuxSession, getTmuxSessionInfo, cleanupOldTmuxSessions, getTmuxResourceUsage, sendCommandToPane, splitPane, listSessionWindows, listWindowPanes, capturePane, getPaneHistory, switchWindow, switchPane, renameWindow, killPane, getDetailedSessionInfo, } from "./tmux.js";
+export { generateLocalSessionName, isLocalTmuxInstalled, listLocalSessions, hasLocalSession, createLocalTmuxSSHSession, sendCommandToLocalSession, captureLocalPane, getLocalPaneHistory, killLocalSession, getLocalSessionInfo, listLocalSessionWindows, listLocalWindowPanes, splitLocalPane, cleanupOldLocalSessions, getLocalTmuxResourceUsage, waitForTextInPane, switchLocalWindow, switchLocalPane, renameLocalWindow, killLocalPane, getDetailedLocalSessionInfo, type LocalTmuxSessionOptions, type LocalTmuxSessionResult, } from "./tmux-local.js";
+export { RESOURCE_COMMANDS } from "./resources.js";
+export type { ResourceCommand } from "./resources.js";