ptn 0.2.7__tar.gz → 0.3.1__tar.gz

{ptn-0.2.7 → ptn-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ptn
-Version: 0.2.7
+Version: 0.3.1
 Summary: Web-based terminal accessible from phone via Cloudflare Tunnel
 Project-URL: Homepage, https://github.com/lyehe/porterminal
 Project-URL: Repository, https://github.com/lyehe/porterminal
@@ -26,6 +26,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: System :: Shells
 Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
 Requires-Python: >=3.12
+Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pywinpty>=2.0.0; sys_platform == 'win32'
@@ -103,6 +104,8 @@ ptn                    # Start in current directory
 ptn ~/projects/myapp   # Start in specific folder
 ptn --no-tunnel        # Local network only
 ptn -b                 # Run in background
+ptn -p                 # Enable password protection
+ptn -dp                # Toggle default password requirement in config
 ptn -v                 # Verbose startup logs
 ptn --init             # Create .ptn/ptn.yaml config
 ptn -V                 # Show version
@@ -129,18 +132,28 @@ buttons:
 update:
   notify_on_startup: true   # Show update notification
   check_interval: 86400     # Seconds between checks (default: 24h)
+
+# Security settings
+security:
+  require_password: true    # Always prompt for password at startup
+  max_auth_attempts: 5      # Max failed attempts before disconnect
 ```
 
 Config is searched in order: `$PORTERMINAL_CONFIG_PATH`, `./ptn.yaml`, `./.ptn/ptn.yaml`, `~/.ptn/ptn.yaml`.
 
 ## Security
 
-> **Warning:** The URL is the only authentication. Anyone with the link has full terminal access.
+Use password if your screen can be exposed to others:
+```bash
+ptn -p                 # Prompt for password this session
+ptn -dp                # Enable password by default (toggle)
+```
+
+Password is per-session (never saved to disk). See [docs/security.md](docs/security.md) for details.
+
+## Troubleshooting
 
-- Don't share the URL
-- Stop the server when not in use (`Ctrl+C`)
-- Use `--no-tunnel` for local network only
-- Environment variables are sanitized (API keys, tokens stripped)
+**Connection fails?** Cloudflare tunnel sometimes blocks connections. Restart the server (`Ctrl+C`, then `ptn`) to get a fresh tunnel URL.
 
 ## Contributing
 

{ptn-0.2.7 → ptn-0.3.1}/README.md

@@ -64,6 +64,8 @@ ptn                    # Start in current directory
 ptn ~/projects/myapp   # Start in specific folder
 ptn --no-tunnel        # Local network only
 ptn -b                 # Run in background
+ptn -p                 # Enable password protection
+ptn -dp                # Toggle default password requirement in config
 ptn -v                 # Verbose startup logs
 ptn --init             # Create .ptn/ptn.yaml config
 ptn -V                 # Show version
@@ -90,18 +92,28 @@ buttons:
 update:
   notify_on_startup: true   # Show update notification
   check_interval: 86400     # Seconds between checks (default: 24h)
+
+# Security settings
+security:
+  require_password: true    # Always prompt for password at startup
+  max_auth_attempts: 5      # Max failed attempts before disconnect
 ```
 
 Config is searched in order: `$PORTERMINAL_CONFIG_PATH`, `./ptn.yaml`, `./.ptn/ptn.yaml`, `~/.ptn/ptn.yaml`.
 
 ## Security
 
-> **Warning:** The URL is the only authentication. Anyone with the link has full terminal access.
+Use password if your screen can be exposed to others:
+```bash
+ptn -p                 # Prompt for password this session
+ptn -dp                # Enable password by default (toggle)
+```
+
+Password is per-session (never saved to disk). See [docs/security.md](docs/security.md) for details.
+
+## Troubleshooting
 
-- Don't share the URL
-- Stop the server when not in use (`Ctrl+C`)
-- Use `--no-tunnel` for local network only
-- Environment variables are sanitized (API keys, tokens stripped)
+**Connection fails?** Cloudflare tunnel sometimes blocks connections. Restart the server (`Ctrl+C`, then `ptn`) to get a fresh tunnel URL.
 
 ## Contributing
 

{ptn-0.2.7 → ptn-0.3.1}/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]:
@@ -314,11 +340,14 @@ def main() -> int:
                 proc.kill()
                 proc.wait()
 
-    cleanup_process(server_process, "server")
-    cleanup_process(tunnel_process, "tunnel")
-
-    # Give processes time to release the port
-    time.sleep(0.5)
+    # 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
 

{ptn-0.2.7 → ptn-0.3.1}/porterminal/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.7'
-__version_tuple__ = version_tuple = (0, 2, 7)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
 __commit_id__ = commit_id = None

{ptn-0.2.7 → ptn-0.3.1}/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)
 

{ptn-0.2.7 → ptn-0.3.1}/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",
 ]

ptn-0.3.1/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."""
+        ...

{ptn-0.2.7 → ptn-0.3.1}/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:

{ptn-0.2.7 → ptn-0.3.1}/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}")

{ptn-0.2.7 → ptn-0.3.1}/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]",
     ]

{ptn-0.2.7 → ptn-0.3.1}/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,
     )

{ptn-0.2.7 → ptn-0.3.1}/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:

{ptn-0.2.7 → ptn-0.3.1}/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

ptn-0.3.1/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)

{ptn-0.2.7 → ptn-0.3.1}/porterminal/infrastructure/server.py

@@ -164,7 +164,7 @@ def start_cloudflared(port: int) -> tuple[subprocess.Popen, str | None]:
 
 
 def drain_process_output(process: subprocess.Popen) -> None:
-    """Drain process output silently (only print errors).
+    """Drain process output silently (only print errors and security warnings).
 
     Args:
         process: Subprocess to drain output from.
@@ -174,8 +174,20 @@ def drain_process_output(process: subprocess.Popen) -> None:
             if not line:
                 break
             line = line.strip()
+            if not line:
+                continue
+            # Always print security warnings and related messages
+            if any(
+                kw in line.lower()
+                for kw in (
+                    "security warning",
+                    "authentication attempts",
+                    "url may have been leaked",
+                )
+            ):
+                console.print(f"[bold red]{line}[/bold red]")
             # Print errors, but ignore harmless ICMP/ping warnings
-            if line and "error" in line.lower() and not _is_icmp_warning(line):
+            elif "error" in line.lower() and not _is_icmp_warning(line):
                 console.print(f"[red]{line}[/red]")
     except (OSError, ValueError):
         pass