ptn 0.2.5__py3-none-any.whl → 0.4.2__py3-none-any.whl

porterminal/composition.py

@@ -14,8 +14,6 @@ from porterminal.application.services import (
 from porterminal.config import find_config_file
 from porterminal.container import Container
 from porterminal.domain import (
-    EnvironmentRules,
-    EnvironmentSanitizer,
     PTYPort,
     SessionLimitChecker,
     ShellCommand,
@@ -29,7 +27,7 @@ from porterminal.infrastructure.repositories import InMemorySessionRepository, I
 
 def create_pty_factory(
     cwd: str | None = None,
-) -> Callable[[ShellCommand, TerminalDimensions, dict[str, str], str | None], PTYPort]:
+) -> Callable[[ShellCommand, TerminalDimensions, str | None], PTYPort]:
     """Create a PTY factory function.
 
     This bridges the domain PTYPort interface with the existing
@@ -40,7 +38,6 @@ def create_pty_factory(
     def factory(
         shell: ShellCommand,
         dimensions: TerminalDimensions,
-        environment: dict[str, str],
         working_directory: str | None = None,
     ) -> PTYPort:
         # Use provided cwd or factory default
@@ -60,6 +57,7 @@ def create_pty_factory(
         )
 
         # Create manager (which implements PTY operations)
+        # Environment sanitization is handled internally by SecurePTYManager
         manager = SecurePTYManager(
             backend=backend,
             shell_config=legacy_shell,
@@ -68,8 +66,6 @@ def create_pty_factory(
             cwd=effective_cwd,
         )
 
-        # Spawn with environment (manager handles sanitization internally,
-        # but we pass our sanitized env to be safe)
         manager.spawn()
 
         return PTYManagerAdapter(manager, dimensions)
@@ -112,6 +108,7 @@ class PTYManagerAdapter:
 def create_container(
     config_path: Path | str | None = None,
     cwd: str | None = None,
+    password_hash: bytes | None = None,
 ) -> Container:
     """Create the dependency container with all wired dependencies.
 
@@ -121,6 +118,7 @@ def create_container(
     Args:
         config_path: Path to config file, or None to search standard locations.
         cwd: Working directory for PTY sessions.
+        password_hash: Bcrypt hash of password for authentication (None = no auth).
 
     Returns:
         Fully wired dependency container.
@@ -141,6 +139,7 @@ def create_container(
     # Get config values with defaults
     server_data = config_data.get("server", {})
     terminal_data = config_data.get("terminal", {})
+    security_data = config_data.get("security", {})
 
     server_host = server_data.get("host", "127.0.0.1")
     server_port = server_data.get("port", 8000)
@@ -148,6 +147,7 @@ def create_container(
     default_rows = terminal_data.get("rows", 30)
     default_shell_id = terminal_data.get("default_shell") or detector.get_default_shell_id()
     buttons = config_data.get("buttons", [])
+    max_auth_attempts = security_data.get("max_auth_attempts", 5)
 
     # Use configured shells if provided, otherwise use detected
     configured_shells = terminal_data.get("shells", [])
@@ -169,7 +169,6 @@ def create_container(
         repository=session_repository,
         pty_factory=pty_factory,
         limit_checker=SessionLimitChecker(),
-        environment_sanitizer=EnvironmentSanitizer(EnvironmentRules()),
         working_directory=cwd,
     )
 
@@ -213,4 +212,6 @@ def create_container(
         default_rows=default_rows,
         buttons=buttons,
         cwd=cwd,
+        password_hash=password_hash,
+        max_auth_attempts=max_auth_attempts,
     )

porterminal/config.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import yaml
 from pydantic import BaseModel, Field, field_validator
 
+from porterminal.domain.values import MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS
 from porterminal.infrastructure.config import ShellDetector
 
 
@@ -43,8 +44,8 @@ class TerminalConfig(BaseModel):
     """Terminal configuration."""
 
     default_shell: str = ""
-    cols: int = Field(default=120, ge=40, le=500)
-    rows: int = Field(default=30, ge=10, le=200)
+    cols: int = Field(default=120, ge=MIN_COLS, le=MAX_COLS)
+    rows: int = Field(default=30, ge=MIN_ROWS, le=MAX_ROWS)
     shells: list[ShellConfig] = Field(default_factory=list)
 
     def get_shell(self, shell_id: str) -> ShellConfig | None:
@@ -60,6 +61,7 @@ class ButtonConfig(BaseModel):
 
     label: str
     send: str | list[str | int] = ""  # string or list of strings/ints (ints = wait ms)
+    row: int = Field(default=1, ge=1, le=10)  # toolbar row (1-10)
 
 
 class CloudflareConfig(BaseModel):
@@ -76,6 +78,13 @@ class UpdateConfig(BaseModel):
     check_interval: int = Field(default=86400, ge=0)  # Seconds between checks (0 = always)
 
 
+class SecurityConfig(BaseModel):
+    """Security configuration."""
+
+    require_password: bool = False  # Prompt for password at startup
+    max_auth_attempts: int = Field(default=5, ge=1, le=100)
+
+
 class Config(BaseModel):
     """Application configuration."""
 
@@ -84,6 +93,7 @@ class Config(BaseModel):
     buttons: list[ButtonConfig] = Field(default_factory=list)
     cloudflare: CloudflareConfig = Field(default_factory=CloudflareConfig)
     update: UpdateConfig = Field(default_factory=UpdateConfig)
+    security: SecurityConfig = Field(default_factory=SecurityConfig)
 
 
 def find_config_file(cwd: Path | None = None) -> Path | None:

porterminal/container.py

@@ -52,3 +52,7 @@ class Container:
 
     # Working directory
     cwd: str | None = None
+
+    # Security
+    password_hash: bytes | None = None
+    max_auth_attempts: int = 5

porterminal/domain/__init__.py

@@ -1,6 +1,5 @@
 """Pure domain layer - no infrastructure dependencies."""
 
-# Value Objects
 # Entities
 from .entities import (
     CLEAR_SCREEN_SEQUENCE,
@@ -23,7 +22,6 @@ from .ports import (
 # Services
 from .services import (
     Clock,
-    EnvironmentSanitizer,
     SessionLimitChecker,
     SessionLimitConfig,
     SessionLimitResult,
@@ -33,13 +31,10 @@ from .services import (
     TokenBucketRateLimiter,
 )
 from .values import (
-    DEFAULT_BLOCKED_VARS,
-    DEFAULT_SAFE_VARS,
     MAX_COLS,
     MAX_ROWS,
     MIN_COLS,
     MIN_ROWS,
-    EnvironmentRules,
     RateLimitConfig,
     SessionId,
     ShellCommand,
@@ -60,9 +55,6 @@ __all__ = [
     "TabId",
     "ShellCommand",
     "RateLimitConfig",
-    "EnvironmentRules",
-    "DEFAULT_SAFE_VARS",
-    "DEFAULT_BLOCKED_VARS",
     # Entities
     "Session",
     "MAX_SESSIONS_PER_USER",
@@ -75,7 +67,6 @@ __all__ = [
     # Services
     "TokenBucketRateLimiter",
     "Clock",
-    "EnvironmentSanitizer",
     "SessionLimitChecker",
     "SessionLimitConfig",
     "SessionLimitResult",

porterminal/domain/entities/output_buffer.py

@@ -9,6 +9,11 @@ OUTPUT_BUFFER_MAX_BYTES = 1_000_000  # 1MB
 # Terminal escape sequence for clear screen (ED2)
 CLEAR_SCREEN_SEQUENCE = b"\x1b[2J"
 
+# Alternate screen buffer sequences (DEC Private Mode)
+# Used by vim, htop, less, tmux, etc.
+ALT_SCREEN_ENTER = (b"\x1b[?47h", b"\x1b[?1047h", b"\x1b[?1049h")
+ALT_SCREEN_EXIT = (b"\x1b[?47l", b"\x1b[?1047l", b"\x1b[?1049l")
+
 
 @dataclass
 class OutputBuffer:
@@ -16,12 +21,21 @@ class OutputBuffer:
 
     Pure domain logic for buffering terminal output.
     No async, no WebSocket - just data management.
+
+    Handles alternate screen buffer (used by vim, htop, less, etc.):
+    - On alt-screen enter: snapshots normal buffer, clears for alt content
+    - On alt-screen exit: restores normal buffer, discards alt content
     """
 
     max_bytes: int = OUTPUT_BUFFER_MAX_BYTES
     _buffer: deque[bytes] = field(default_factory=deque)
     _size: int = 0
 
+    # Alt-screen state
+    _in_alt_screen: bool = False
+    _normal_snapshot: deque[bytes] | None = None
+    _normal_snapshot_size: int = 0
+
     @property
     def size(self) -> int:
         """Current buffer size in bytes."""
@@ -32,12 +46,53 @@ class OutputBuffer:
         """Check if buffer is empty."""
         return self._size == 0
 
+    @property
+    def in_alt_screen(self) -> bool:
+        """Check if currently in alternate screen mode."""
+        return self._in_alt_screen
+
+    def _enter_alt_screen(self) -> None:
+        """Handle alt-screen entry: snapshot normal buffer."""
+        if self._in_alt_screen:
+            return  # Already in alt-screen, ignore nested
+        self._in_alt_screen = True
+        self._normal_snapshot = self._buffer.copy()
+        self._normal_snapshot_size = self._size
+        self._clear_buffer()
+
+    def _exit_alt_screen(self) -> None:
+        """Handle alt-screen exit: restore normal buffer."""
+        if not self._in_alt_screen:
+            return  # Not in alt-screen, ignore
+        self._in_alt_screen = False
+        if self._normal_snapshot is not None:
+            self._buffer = self._normal_snapshot
+            self._size = self._normal_snapshot_size
+            self._normal_snapshot = None
+            self._normal_snapshot_size = 0
+
+    def _clear_buffer(self) -> None:
+        """Clear the buffer contents only."""
+        self._buffer.clear()
+        self._size = 0
+
     def add(self, data: bytes) -> None:
         """Add data to the buffer.
 
-        Handles clear screen detection and size limits.
+        Handles alt-screen transitions, clear screen detection, and size limits.
         When clear screen is detected, only keep content AFTER the last clear sequence.
         """
+        # Check alt-screen transitions FIRST
+        for pattern in ALT_SCREEN_EXIT:
+            if pattern in data:
+                self._exit_alt_screen()
+                break
+        else:
+            for pattern in ALT_SCREEN_ENTER:
+                if pattern in data:
+                    self._enter_alt_screen()
+                    return  # Don't buffer alt-screen enter data
+
         # Check for clear screen sequence
         if CLEAR_SCREEN_SEQUENCE in data:
             # Clear old buffer

porterminal/domain/entities/tab.py

@@ -13,6 +13,15 @@ TAB_NAME_MIN_LENGTH = 1
 TAB_NAME_MAX_LENGTH = 50
 
 
+def _validate_tab_name(name: str) -> None:
+    """Validate tab name length."""
+    if not (TAB_NAME_MIN_LENGTH <= len(name) <= TAB_NAME_MAX_LENGTH):
+        raise ValueError(
+            f"Tab name must be {TAB_NAME_MIN_LENGTH}-{TAB_NAME_MAX_LENGTH} "
+            f"characters, got {len(name)}"
+        )
+
+
 @dataclass
 class Tab:
     """Terminal tab entity.
@@ -35,11 +44,7 @@ class Tab:
     last_accessed: datetime
 
     def __post_init__(self) -> None:
-        if not (TAB_NAME_MIN_LENGTH <= len(self.name) <= TAB_NAME_MAX_LENGTH):
-            raise ValueError(
-                f"Tab name must be {TAB_NAME_MIN_LENGTH}-{TAB_NAME_MAX_LENGTH} "
-                f"characters, got {len(self.name)}"
-            )
+        _validate_tab_name(self.name)
 
     @property
     def tab_id(self) -> str:
@@ -52,11 +57,7 @@ class Tab:
 
     def rename(self, new_name: str) -> None:
         """Rename the tab with validation."""
-        if not (TAB_NAME_MIN_LENGTH <= len(new_name) <= TAB_NAME_MAX_LENGTH):
-            raise ValueError(
-                f"Tab name must be {TAB_NAME_MIN_LENGTH}-{TAB_NAME_MAX_LENGTH} "
-                f"characters, got {len(new_name)}"
-            )
+        _validate_tab_name(new_name)
         self.name = new_name
 
     def to_dict(self) -> dict:

porterminal/domain/services/__init__.py

@@ -1,6 +1,5 @@
 """Domain services - pure business logic operations."""
 
-from .environment_sanitizer import EnvironmentSanitizer
 from .rate_limiter import Clock, TokenBucketRateLimiter
 from .session_limits import SessionLimitChecker, SessionLimitConfig, SessionLimitResult
 from .tab_limits import TabLimitChecker, TabLimitConfig, TabLimitResult
@@ -8,7 +7,6 @@ from .tab_limits import TabLimitChecker, TabLimitConfig, TabLimitResult
 __all__ = [
     "TokenBucketRateLimiter",
     "Clock",
-    "EnvironmentSanitizer",
     "SessionLimitChecker",
     "SessionLimitConfig",
     "SessionLimitResult",

porterminal/domain/values/__init__.py

@@ -1,6 +1,5 @@
 """Domain value objects - immutable data structures."""
 
-from .environment_rules import DEFAULT_BLOCKED_VARS, DEFAULT_SAFE_VARS, EnvironmentRules
 from .rate_limit_config import RateLimitConfig
 from .session_id import SessionId
 from .shell_command import ShellCommand
@@ -19,7 +18,4 @@ __all__ = [
     "TabId",
     "ShellCommand",
     "RateLimitConfig",
-    "EnvironmentRules",
-    "DEFAULT_SAFE_VARS",
-    "DEFAULT_BLOCKED_VARS",
 ]

porterminal/domain/values/environment_rules.py

@@ -22,12 +22,15 @@ DEFAULT_SAFE_VARS: frozenset[str] = frozenset(
         "HOMEPATH",
         "LOCALAPPDATA",
         "APPDATA",
+        "PROGRAMDATA",
         "PROGRAMFILES",
         "PROGRAMFILES(X86)",
         "COMMONPROGRAMFILES",
         # System info
         "COMPUTERNAME",
         "USERNAME",
+        "USER",
+        "LOGNAME",
         "USERDOMAIN",
         "OS",
         "PROCESSOR_ARCHITECTURE",

porterminal/infrastructure/auth.py

@@ -0,0 +1,131 @@
+"""Authentication utilities for WebSocket connections."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+from typing import TYPE_CHECKING
+
+import bcrypt
+
+if TYPE_CHECKING:
+    from porterminal.application.ports import ConnectionPort
+
+logger = logging.getLogger(__name__)
+
+
+def _shutdown_server() -> None:
+    """Trigger server shutdown due to auth failure."""
+    import time
+
+    # Print plain text - parent's drain_process_output handles formatting
+    print("", flush=True)
+    print("SECURITY WARNING", flush=True)
+    print("Max authentication attempts exceeded.", flush=True)
+    print("Your URL may have been leaked. Investigate before restarting.", flush=True)
+    print("", flush=True)
+
+    logger.warning(
+        "SECURITY: Max authentication attempts exceeded. "
+        "Shutting down server to prevent brute force attack."
+    )
+
+    # Delay to ensure message is visible before shutdown
+    time.sleep(1)
+    os.kill(os.getpid(), signal.SIGTERM)
+
+
+async def authenticate_connection(
+    connection: ConnectionPort,
+    password_hash: bytes,
+    max_attempts: int = 5,
+    timeout_seconds: int = 30,
+) -> bool:
+    """Authenticate a WebSocket connection with password.
+
+    Sends auth_required, waits for auth message, validates password.
+    Returns True if authenticated, False otherwise.
+
+    Args:
+        connection: WebSocket connection adapter
+        password_hash: bcrypt hash of the expected password
+        max_attempts: Maximum number of password attempts
+        timeout_seconds: Timeout for receiving auth message
+
+    Returns:
+        True if successfully authenticated, False otherwise
+    """
+    await connection.send_message({"type": "auth_required"})
+
+    attempts = 0
+    while attempts < max_attempts:
+        try:
+            message = await asyncio.wait_for(connection.receive(), timeout=timeout_seconds)
+        except TimeoutError:
+            await connection.send_message(
+                {
+                    "type": "auth_failed",
+                    "attempts_remaining": 0,
+                    "error": "Authentication timeout",
+                }
+            )
+            return False
+
+        if not isinstance(message, dict) or message.get("type") != "auth":
+            await connection.send_message(
+                {
+                    "type": "error",
+                    "error": "Authentication required",
+                }
+            )
+            continue
+
+        password = message.get("password", "")
+        if bcrypt.checkpw(password.encode(), password_hash):
+            await connection.send_message({"type": "auth_success"})
+            return True
+
+        attempts += 1
+        remaining = max_attempts - attempts
+        await connection.send_message(
+            {
+                "type": "auth_failed",
+                "attempts_remaining": remaining,
+                "error": "Invalid password" if remaining > 0 else "Too many failed attempts",
+            }
+        )
+
+    # Max attempts exhausted - shutdown to prevent brute force
+    _shutdown_server()
+    return False
+
+
+async def validate_auth_message(
+    connection: ConnectionPort,
+    password_hash: bytes,
+    timeout_seconds: int = 10,
+) -> bool:
+    """Validate a single auth message from a connection.
+
+    For terminal WebSocket where we expect auth as first message.
+
+    Args:
+        connection: WebSocket connection adapter
+        password_hash: bcrypt hash of the expected password
+        timeout_seconds: Timeout for receiving auth message
+
+    Returns:
+        True if valid, False otherwise
+    """
+    try:
+        message = await asyncio.wait_for(connection.receive(), timeout=timeout_seconds)
+    except TimeoutError:
+        return False
+
+    if not isinstance(message, dict) or message.get("type") != "auth":
+        return False
+
+    password = message.get("password", "")
+    return bcrypt.checkpw(password.encode(), password_hash)

porterminal/infrastructure/cloudflared.py

@@ -17,6 +17,13 @@ console = Console()
 class CloudflaredInstaller:
     """Platform-specific cloudflared installer."""
 
+    @staticmethod
+    def _add_to_path(path: str | Path) -> None:
+        """Add directory to PATH for current process."""
+        path_str = str(path)
+        os.environ["PATH"] = path_str + os.pathsep + os.environ.get("PATH", "")
+        console.print(f"[dim]Added to PATH: {path_str}[/dim]")
+
     @staticmethod
     def is_installed() -> bool:
         """Check if cloudflared is installed."""
@@ -91,8 +98,7 @@ class CloudflaredInstaller:
                     # Try to find and add to PATH for current session
                     install_path = CloudflaredInstaller._find_cloudflared_windows()
                     if install_path:
-                        os.environ["PATH"] = install_path + os.pathsep + os.environ.get("PATH", "")
-                        console.print(f"[dim]Added to PATH: {install_path}[/dim]")
+                        CloudflaredInstaller._add_to_path(install_path)
                     # Return True regardless - winget succeeded, may just need shell restart
                     return True
             except (subprocess.TimeoutExpired, OSError) as e:
@@ -119,7 +125,7 @@ class CloudflaredInstaller:
 
             exe_path = install_dir / "cloudflared.exe"
             if exe_path.exists():
-                os.environ["PATH"] = str(install_dir) + os.pathsep + os.environ.get("PATH", "")
+                CloudflaredInstaller._add_to_path(install_dir)
                 console.print(f"[green]✓ Installed to {install_dir}[/green]")
                 return True
 
@@ -172,12 +178,16 @@ class CloudflaredInstaller:
                 try:
                     # Add Cloudflare repo first for apt
                     if name == "apt":
+                        # Use "any" distribution - works on all Debian-based systems
+                        # (Ubuntu, Debian, Mint, Pop!_OS, etc.) without codename detection
+                        # See: https://pkg.cloudflare.com/
                         subprocess.run(
                             [
                                 "bash",
                                 "-c",
+                                "sudo mkdir -p --mode=0755 /usr/share/keyrings && "
                                 "curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null && "
-                                "echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main' | sudo tee /etc/apt/sources.list.d/cloudflared.list && "
+                                "echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list && "
                                 "sudo apt-get update",
                             ],
                             capture_output=True,
@@ -199,10 +209,7 @@ class CloudflaredInstaller:
                         # Try to find and add to PATH
                         install_path = CloudflaredInstaller._find_cloudflared_unix()
                         if install_path:
-                            os.environ["PATH"] = (
-                                install_path + os.pathsep + os.environ.get("PATH", "")
-                            )
-                            console.print(f"[dim]Added to PATH: {install_path}[/dim]")
+                            CloudflaredInstaller._add_to_path(install_path)
                         # Return True regardless - package manager succeeded
                         return True
                 except (subprocess.TimeoutExpired, OSError) as e:
@@ -222,7 +229,7 @@ class CloudflaredInstaller:
             os.chmod(bin_path, 0o755)
 
             # Add to PATH for this session
-            os.environ["PATH"] = str(install_dir) + os.pathsep + os.environ.get("PATH", "")
+            CloudflaredInstaller._add_to_path(install_dir)
             console.print(f"[green]✓ Installed to {bin_path}[/green]")
             return True
 
@@ -253,8 +260,7 @@ class CloudflaredInstaller:
                     # Try to find and add to PATH
                     install_path = CloudflaredInstaller._find_cloudflared_unix()
                     if install_path:
-                        os.environ["PATH"] = install_path + os.pathsep + os.environ.get("PATH", "")
-                        console.print(f"[dim]Added to PATH: {install_path}[/dim]")
+                        CloudflaredInstaller._add_to_path(install_path)
                     # Return True regardless - Homebrew succeeded
                     return True
             except (subprocess.TimeoutExpired, OSError) as e:
@@ -285,7 +291,7 @@ class CloudflaredInstaller:
             bin_path = install_dir / "cloudflared"
             if bin_path.exists():
                 os.chmod(bin_path, 0o755)
-                os.environ["PATH"] = str(install_dir) + os.pathsep + os.environ.get("PATH", "")
+                CloudflaredInstaller._add_to_path(install_dir)
                 console.print(f"[green]✓ Installed to {bin_path}[/green]")
                 return True