ptn 0.2.7__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ptn
-Version: 0.2.7
+Version: 0.4.2
 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'
@@ -74,9 +75,10 @@ So I built something simpler: **run a command, scan a QR, start typing.**
 ## Features
 
 - **One command, instant access** - No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
-- **Actually usable on mobile** - Essential buttons and gestures for everyday terminal use.
-- **Multi-tab shared sessions** - Run builds in one tab, tail logs in another. Sessions and tabs persist across reconnects.
-- **Cross-platform** - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish). Auto-detects your shells.
+- **Actually usable on mobile** - Touch-optimized with momentum scrolling, pinch-to-zoom, swipe gestures, and modifier keys (Ctrl, Alt).
+- **Full terminal apps** - vim, htop, less, tmux all work correctly with proper alt-screen buffer handling.
+- **Persistent multi-tab sessions** - Sessions survive disconnects. Close the browser, switch networks, reconnect from another device—your shell and running processes are still there. Multiple devices can view the same session simultaneously.
+- **Cross-platform** - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, and any shell via `$SHELL`). Auto-detects your shells.
 
 ## Install
 
@@ -101,46 +103,95 @@ Requires Python 3.12+ and [cloudflared](https://developers.cloudflare.com/cloudf
 ```bash
 ptn                    # Start in current directory
 ptn ~/projects/myapp   # Start in specific folder
-ptn --no-tunnel        # Local network only
-ptn -b                 # Run in background
-ptn -v                 # Verbose startup logs
-ptn --init             # Create .ptn/ptn.yaml config
-ptn -V                 # Show version
-ptn -U                 # Update to latest version
-ptn --check-update     # Check if update available
 ```
 
+| Flag | Description |
+|------|-------------|
+| `-n, --no-tunnel` | Local network only (no Cloudflare tunnel) |
+| `-b, --background` | Run in background and return immediately |
+| `-p, --password` | Prompt for password to protect this session |
+| `-dp, --default-password` | Toggle password requirement in config (on/off) |
+| `-v, --verbose` | Show detailed startup logs |
+| `-i, --init` | Create `.ptn/ptn.yaml` config with auto-discovered project scripts |
+| `-u, --update` | Update to the latest version |
+| `-c, --check-update` | Check if a newer version is available |
+| `-V, --version` | Show version |
+
+## Mobile Gestures
+
+| Gesture | Action |
+|---------|--------|
+| **Tap** | Focus terminal, clear selection |
+| **Long-press** | Start text selection |
+| **Double-tap** | Select word |
+| **Swipe left/right** | Arrow keys (← →) |
+| **Scroll** | Momentum scrolling with physics |
+| **Pinch** | Zoom text (10-24px) |
+
+**Modifier keys** (Ctrl, Alt, Shift): Tap once for sticky (one keystroke), double-tap for lock.
+
 ## Configuration
 
-Run `ptn --init` to create a starter config, or create `ptn.yaml` manually:
+Run `ptn --init` to create a starter config. It auto-discovers project scripts from `package.json`, `pyproject.toml`, or `Makefile` and adds them as buttons:
+
+```bash
+ptn -i
+# Created: .ptn/ptn.yaml
+# Discovered 3 project script(s): build, dev, test
+```
+
+Or create `ptn.yaml` manually:
 
 ```yaml
+# Terminal settings
+terminal:
+  default_shell: nu              # Default shell ID
+  shells:                        # Custom shell definitions
+    - id: nu
+      name: Nushell
+      command: nu
+      args: []
+
 # Custom buttons (appear in toolbar)
+# row: 1 = default row, 2+ = additional rows
 buttons:
   - label: "claude"
     send:
       - "claude"
       - 100        # delay in ms
       - "\r"
-  - label: "tmux"
-    send: "tmux\r"
+  - label: "build"
+    send: "npm run build\r"
+    row: 2         # second button row
 
 # Update checker settings
 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
+
+**Connection fails?** Cloudflare tunnel sometimes blocks connections. Restart the server (`Ctrl+C`, then `ptn`) to get a fresh tunnel URL.
 
-- 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)
+**Shell not detected?** Set your `$SHELL` environment variable or configure shells in `ptn.yaml`.
 
 ## Contributing
 

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

@@ -35,9 +35,10 @@ So I built something simpler: **run a command, scan a QR, start typing.**
 ## Features
 
 - **One command, instant access** - No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
-- **Actually usable on mobile** - Essential buttons and gestures for everyday terminal use.
-- **Multi-tab shared sessions** - Run builds in one tab, tail logs in another. Sessions and tabs persist across reconnects.
-- **Cross-platform** - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish). Auto-detects your shells.
+- **Actually usable on mobile** - Touch-optimized with momentum scrolling, pinch-to-zoom, swipe gestures, and modifier keys (Ctrl, Alt).
+- **Full terminal apps** - vim, htop, less, tmux all work correctly with proper alt-screen buffer handling.
+- **Persistent multi-tab sessions** - Sessions survive disconnects. Close the browser, switch networks, reconnect from another device—your shell and running processes are still there. Multiple devices can view the same session simultaneously.
+- **Cross-platform** - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, and any shell via `$SHELL`). Auto-detects your shells.
 
 ## Install
 
@@ -62,46 +63,95 @@ Requires Python 3.12+ and [cloudflared](https://developers.cloudflare.com/cloudf
 ```bash
 ptn                    # Start in current directory
 ptn ~/projects/myapp   # Start in specific folder
-ptn --no-tunnel        # Local network only
-ptn -b                 # Run in background
-ptn -v                 # Verbose startup logs
-ptn --init             # Create .ptn/ptn.yaml config
-ptn -V                 # Show version
-ptn -U                 # Update to latest version
-ptn --check-update     # Check if update available
 ```
 
+| Flag | Description |
+|------|-------------|
+| `-n, --no-tunnel` | Local network only (no Cloudflare tunnel) |
+| `-b, --background` | Run in background and return immediately |
+| `-p, --password` | Prompt for password to protect this session |
+| `-dp, --default-password` | Toggle password requirement in config (on/off) |
+| `-v, --verbose` | Show detailed startup logs |
+| `-i, --init` | Create `.ptn/ptn.yaml` config with auto-discovered project scripts |
+| `-u, --update` | Update to the latest version |
+| `-c, --check-update` | Check if a newer version is available |
+| `-V, --version` | Show version |
+
+## Mobile Gestures
+
+| Gesture | Action |
+|---------|--------|
+| **Tap** | Focus terminal, clear selection |
+| **Long-press** | Start text selection |
+| **Double-tap** | Select word |
+| **Swipe left/right** | Arrow keys (← →) |
+| **Scroll** | Momentum scrolling with physics |
+| **Pinch** | Zoom text (10-24px) |
+
+**Modifier keys** (Ctrl, Alt, Shift): Tap once for sticky (one keystroke), double-tap for lock.
+
 ## Configuration
 
-Run `ptn --init` to create a starter config, or create `ptn.yaml` manually:
+Run `ptn --init` to create a starter config. It auto-discovers project scripts from `package.json`, `pyproject.toml`, or `Makefile` and adds them as buttons:
+
+```bash
+ptn -i
+# Created: .ptn/ptn.yaml
+# Discovered 3 project script(s): build, dev, test
+```
+
+Or create `ptn.yaml` manually:
 
 ```yaml
+# Terminal settings
+terminal:
+  default_shell: nu              # Default shell ID
+  shells:                        # Custom shell definitions
+    - id: nu
+      name: Nushell
+      command: nu
+      args: []
+
 # Custom buttons (appear in toolbar)
+# row: 1 = default row, 2+ = additional rows
 buttons:
   - label: "claude"
     send:
       - "claude"
       - 100        # delay in ms
       - "\r"
-  - label: "tmux"
-    send: "tmux\r"
+  - label: "build"
+    send: "npm run build\r"
+    row: 2         # second button row
 
 # Update checker settings
 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
+
+**Connection fails?** Cloudflare tunnel sometimes blocks connections. Restart the server (`Ctrl+C`, then `ptn`) to get a fresh tunnel URL.
 
-- 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)
+**Shell not detected?** Set your `$SHELL` environment variable or configure shells in `ptn.yaml`.
 
 ## Contributing
 

{ptn-0.2.7 → ptn-0.4.2}/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.4.2}/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.4.2'
+__version_tuple__ = version_tuple = (0, 4, 2)
 
 __commit_id__ = commit_id = None

{ptn-0.2.7 → ptn-0.4.2}/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.4.2}/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.4.2/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.4.2}/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:
@@ -37,6 +36,23 @@ class ManagementService:
         self._get_shell = shell_provider
         self._default_dims = default_dimensions
 
+    async def _send_error(
+        self,
+        connection: ConnectionPort,
+        response_type: str,
+        request_id: str,
+        error: str,
+    ) -> None:
+        """Send an error response to a connection."""
+        await connection.send_message(
+            {
+                "type": response_type,
+                "request_id": request_id,
+                "success": False,
+                "error": error,
+            }
+        )
+
     async def handle_message(
         self,
         user_id: UserId,
@@ -77,13 +93,8 @@ class ManagementService:
             # Get shell
             shell = self._get_shell(shell_id)
             if not shell:
-                await connection.send_message(
-                    {
-                        "type": "create_tab_response",
-                        "request_id": request_id,
-                        "success": False,
-                        "error": "Invalid shell",
-                    }
+                await self._send_error(
+                    connection, "create_tab_response", request_id, "Invalid shell"
                 )
                 return
 
@@ -128,14 +139,7 @@ class ManagementService:
 
         except ValueError as e:
             logger.warning("Tab creation failed: %s", e)
-            await connection.send_message(
-                {
-                    "type": "create_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": str(e),
-                }
-            )
+            await self._send_error(connection, "create_tab_response", request_id, str(e))
 
     async def _handle_close_tab(
         self,
@@ -148,27 +152,13 @@ class ManagementService:
         tab_id = message.get("tab_id")
 
         if not tab_id:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Missing tab_id",
-                }
-            )
+            await self._send_error(connection, "close_tab_response", request_id, "Missing tab_id")
             return
 
         # Get tab and session info before closing
         tab = self._tab_service.get_tab(tab_id)
         if not tab:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Tab not found",
-                }
-            )
+            await self._send_error(connection, "close_tab_response", request_id, "Tab not found")
             return
 
         session_id = tab.session_id
@@ -176,13 +166,8 @@ class ManagementService:
         # Close the tab
         closed_tab = self._tab_service.close_tab(tab_id, user_id)
         if not closed_tab:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Failed to close tab",
-                }
+            await self._send_error(
+                connection, "close_tab_response", request_id, "Failed to close tab"
             )
             return
 
@@ -223,26 +208,16 @@ class ManagementService:
         new_name = message.get("name")
 
         if not tab_id or not new_name:
-            await connection.send_message(
-                {
-                    "type": "rename_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Missing tab_id or name",
-                }
+            await self._send_error(
+                connection, "rename_tab_response", request_id, "Missing tab_id or name"
             )
             return
 
         # Rename the tab
         tab = self._tab_service.rename_tab(tab_id, user_id, new_name)
         if not tab:
-            await connection.send_message(
-                {
-                    "type": "rename_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Failed to rename tab",
-                }
+            await self._send_error(
+                connection, "rename_tab_response", request_id, "Failed to rename tab"
             )
             return
 

{ptn-0.2.7 → ptn-0.4.2}/porterminal/application/services/session_service.py

@@ -2,14 +2,11 @@
 
 import asyncio
 import logging
-import os
 import uuid
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 
 from porterminal.domain import (
-    EnvironmentRules,
-    EnvironmentSanitizer,
     PTYPort,
     Session,
     SessionId,
@@ -32,17 +29,13 @@ class SessionService:
     def __init__(
         self,
         repository: SessionRepository[PTYPort],
-        pty_factory: Callable[
-            [ShellCommand, TerminalDimensions, dict[str, str], str | None], PTYPort
-        ],
+        pty_factory: Callable[[ShellCommand, TerminalDimensions, str | None], PTYPort],
         limit_checker: SessionLimitChecker | None = None,
-        environment_sanitizer: EnvironmentSanitizer | None = None,
         working_directory: str | None = None,
     ) -> None:
         self._repository = repository
         self._pty_factory = pty_factory
         self._limit_checker = limit_checker or SessionLimitChecker()
-        self._sanitizer = environment_sanitizer or EnvironmentSanitizer(EnvironmentRules())
         self._cwd = working_directory
         self._running = False
         self._cleanup_task: asyncio.Task | None = None
@@ -108,9 +101,8 @@ class SessionService:
         if not limit_result.allowed:
             raise ValueError(limit_result.reason)
 
-        # Create PTY with sanitized environment
-        env = self._sanitizer.sanitize(dict(os.environ))
-        pty = self._pty_factory(shell, dimensions, env, self._cwd)
+        # Create PTY (environment sanitization handled by PTY layer)
+        pty = self._pty_factory(shell, dimensions, self._cwd)
 
         # Create session (starts with 0 clients, caller adds via add_client())
         now = datetime.now(UTC)