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

porterminal/__init__.py

@@ -14,6 +14,7 @@ except ImportError:
     __version__ = "0.0.0-dev"  # Fallback before first build
 
 import os
+import signal
 import subprocess
 import sys
 import time
@@ -149,6 +150,30 @@ def main() -> int:
     check_and_notify()
     verbose = args.verbose
 
+    # Load config to check require_password setting
+    from porterminal.config import get_config
+
+    config = get_config()
+
+    # Handle password mode (CLI flag or config setting)
+    if args.password or config.security.require_password:
+        import getpass
+
+        try:
+            password = getpass.getpass("Enter password: ")
+            if not password:
+                console.print("[red]Error:[/red] Password cannot be empty")
+                return 1
+
+            import bcrypt
+
+            password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt())
+            os.environ["PORTERMINAL_PASSWORD_HASH"] = password_hash.decode()
+            console.print("[green]Password protection enabled[/green]")
+        except KeyboardInterrupt:
+            console.print("\n[dim]Cancelled[/dim]")
+            return 0
+
     # Handle background mode
     if args.background:
         return _run_in_background(args)
@@ -170,9 +195,6 @@ def main() -> int:
         cwd_str = str(cwd)
         os.environ["PORTERMINAL_CWD"] = cwd_str
 
-    from porterminal.config import get_config
-
-    config = get_config()
     bind_host = config.server.host
     preferred_port = config.server.port
     port = preferred_port
@@ -226,6 +248,10 @@ def main() -> int:
             status.update("[cyan]Establishing tunnel...[/cyan]")
             tunnel_process, tunnel_url = start_cloudflared(port)
 
+            if tunnel_url:
+                # Wait for tunnel to stabilize before showing URL
+                time.sleep(1)
+
             if not tunnel_url:
                 console.print("[red]Error:[/red] Failed to establish tunnel")
                 for proc in [server_process, tunnel_process]:
@@ -287,15 +313,41 @@ def main() -> int:
     def cleanup_process(proc: subprocess.Popen | None, name: str) -> None:
         if proc is None or proc.poll() is not None:
             return
-        try:
-            proc.terminate()
-            proc.wait(timeout=5)
-        except subprocess.TimeoutExpired:
-            proc.kill()
-            proc.wait()  # Reap the killed process
 
-    cleanup_process(server_process, "server")
-    cleanup_process(tunnel_process, "tunnel")
+        if sys.platform == "win32":
+            # Windows: use taskkill /T to kill entire process tree
+            try:
+                subprocess.run(
+                    ["taskkill", "/T", "/F", "/PID", str(proc.pid)],
+                    capture_output=True,
+                    timeout=10,
+                )
+                # Wait for process to actually terminate
+                proc.wait(timeout=5)
+            except (subprocess.TimeoutExpired, OSError):
+                # Last resort: try to kill just the main process
+                try:
+                    proc.kill()
+                    proc.wait(timeout=2)
+                except (OSError, subprocess.TimeoutExpired):
+                    pass
+        else:
+            # Unix: terminate gracefully, then kill
+            try:
+                proc.terminate()
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+
+    # Ignore Ctrl+C during cleanup to prevent orphaned processes
+    # Cleanup has timeouts so it won't hang forever
+    old_handler = signal.signal(signal.SIGINT, signal.SIG_IGN)
+    try:
+        cleanup_process(server_process, "server")
+        cleanup_process(tunnel_process, "tunnel")
+    finally:
+        signal.signal(signal.SIGINT, old_handler)
 
     return 0
 

porterminal/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.3.2'
+__version_tuple__ = version_tuple = (0, 3, 2)
 
 __commit_id__ = commit_id = None

porterminal/app.py

@@ -17,6 +17,7 @@ from . import __version__
 from .composition import create_container
 from .container import Container
 from .domain import UserId
+from .infrastructure.auth import authenticate_connection, validate_auth_message
 from .infrastructure.web import FastAPIWebSocketAdapter
 from .logging_setup import setup_logging_from_env
 
@@ -55,7 +56,12 @@ async def lifespan(app: FastAPI):
     # config_path=None uses find_config_file() to search standard locations
     cwd = os.environ.get("PORTERMINAL_CWD")
 
-    container = create_container(config_path=None, cwd=cwd)
+    # Get password hash from environment if set
+    password_hash = None
+    if hash_str := os.environ.get("PORTERMINAL_PASSWORD_HASH"):
+        password_hash = hash_str.encode()
+
+    container = create_container(config_path=None, cwd=cwd, password_hash=password_hash)
     app.state.container = container
 
     # Wire up cascade: when session is destroyed, close associated tabs and broadcast
@@ -225,6 +231,17 @@ def create_app() -> FastAPI:
         )
 
         try:
+            # Authentication phase if password is set
+            if container.password_hash is not None:
+                authenticated = await authenticate_connection(
+                    connection,
+                    container.password_hash,
+                    max_attempts=container.max_auth_attempts,
+                )
+                if not authenticated:
+                    await websocket.close(code=4001, reason="Auth failed")
+                    return
+
             # Register for broadcasts
             await connection_registry.register(user_id, connection)
 
@@ -333,6 +350,13 @@ def create_app() -> FastAPI:
             session.session_id,
         )
 
+        # Authentication check if password is set
+        if container.password_hash is not None:
+            if not await validate_auth_message(connection, container.password_hash):
+                logger.warning("Terminal WebSocket auth failed user_id=%s", user_id)
+                await websocket.close(code=4001, reason="Auth failed")
+                return
+
         # Update tab access time
         tab_service.touch_tab(tab_id, user_id)
 

porterminal/application/ports/__init__.py

@@ -1,7 +1,9 @@
 """Application layer ports - interfaces for presentation layer."""
 
 from .connection_port import ConnectionPort
+from .connection_registry_port import ConnectionRegistryPort
 
 __all__ = [
     "ConnectionPort",
+    "ConnectionRegistryPort",
 ]

porterminal/application/ports/connection_registry_port.py

@@ -0,0 +1,46 @@
+"""Connection registry port - interface for broadcasting to user connections."""
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from porterminal.domain import UserId
+
+    from .connection_port import ConnectionPort
+
+
+class ConnectionRegistryPort(Protocol):
+    """Protocol for managing and broadcasting to user connections.
+
+    Infrastructure layer (e.g., UserConnectionRegistry) implements this.
+    Application layer uses this interface for broadcasting messages.
+    """
+
+    async def register(self, user_id: "UserId", connection: "ConnectionPort") -> None:
+        """Register a new connection for a user."""
+        ...
+
+    async def unregister(self, user_id: "UserId", connection: "ConnectionPort") -> None:
+        """Unregister a connection."""
+        ...
+
+    async def broadcast(
+        self,
+        user_id: "UserId",
+        message: dict[str, Any],
+        exclude: "ConnectionPort | None" = None,
+    ) -> int:
+        """Send message to all connections for a user.
+
+        Args:
+            user_id: User to broadcast to.
+            message: Message dict to send.
+            exclude: Optional connection to exclude (e.g., the sender).
+
+        Returns:
+            Number of connections sent to.
+        """
+        ...
+
+    def total_connections(self) -> int:
+        """Get total number of connections across all users."""
+        ...

porterminal/application/services/management_service.py

@@ -3,7 +3,7 @@
 import logging
 from collections.abc import Callable
 
-from porterminal.application.ports import ConnectionPort
+from porterminal.application.ports import ConnectionPort, ConnectionRegistryPort
 from porterminal.application.services.session_service import SessionService
 from porterminal.application.services.tab_service import TabService
 from porterminal.domain import (
@@ -11,7 +11,6 @@ from porterminal.domain import (
     TerminalDimensions,
     UserId,
 )
-from porterminal.infrastructure.registry import UserConnectionRegistry
 
 logger = logging.getLogger(__name__)
 
@@ -27,7 +26,7 @@ class ManagementService:
         self,
         session_service: SessionService,
         tab_service: TabService,
-        connection_registry: UserConnectionRegistry,
+        connection_registry: ConnectionRegistryPort,
         shell_provider: Callable[[str | None], ShellCommand | None],
         default_dimensions: TerminalDimensions,
     ) -> None:

porterminal/cli/args.py

@@ -66,6 +66,18 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Create .ptn/ptn.yaml config file in current directory",
     )
+    parser.add_argument(
+        "-p",
+        "--password",
+        action="store_true",
+        help="Prompt for password to protect terminal access",
+    )
+    parser.add_argument(
+        "-dp",
+        "--default-password",
+        action="store_true",
+        help="Toggle password requirement in config (on/off)",
+    )
     # Internal argument for background mode communication
     parser.add_argument(
         "--_url-file",
@@ -97,6 +109,10 @@ def parse_args() -> argparse.Namespace:
         _init_config()
         sys.exit(0)
 
+    if args.default_password:
+        _toggle_password_requirement()
+        sys.exit(0)
+
     return args
 
 
@@ -139,3 +155,40 @@ def _init_config() -> None:
     config_dir.mkdir(exist_ok=True)
     config_file.write_text(DEFAULT_CONFIG)
     print(f"Created: {config_file}")
+
+
+def _toggle_password_requirement() -> None:
+    """Toggle security.require_password in config file."""
+    from pathlib import Path
+
+    import yaml
+
+    from porterminal.config import find_config_file
+
+    # Find existing config or use default location
+    config_path = find_config_file()
+    if config_path is None:
+        config_dir = Path.cwd() / ".ptn"
+        config_path = config_dir / "ptn.yaml"
+        config_dir.mkdir(exist_ok=True)
+
+    # Read existing config or create empty
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    else:
+        data = {}
+
+    # Toggle the value
+    if "security" not in data:
+        data["security"] = {}
+    current = data["security"].get("require_password", False)
+    data["security"]["require_password"] = not current
+
+    # Write back
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
+
+    new_value = data["security"]["require_password"]
+    status = "enabled" if new_value else "disabled"
+    print(f"Password requirement {status} in {config_path}")

porterminal/cli/display.py

@@ -136,7 +136,7 @@ def display_startup_screen(
         *tagline_colored,
         "",
         f"[bold yellow]{get_caution()}[/bold yellow]",
-        "[bright_red]The URL is the only security. Use at your own risk.[/bright_red]",
+        "[dim]Use -p for password protection if your screen is exposed[/dim]",
         status,
         f"[bold cyan]{url}[/bold cyan]",
     ]

porterminal/composition.py

@@ -112,6 +112,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 +122,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 +143,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 +151,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", [])
@@ -213,4 +217,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

@@ -76,6 +76,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 +91,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/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

@@ -172,12 +172,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,