ptn 0.1.4__py3-none-any.whl

porterminal/domain/ports/session_repository.py

@@ -0,0 +1,58 @@
+"""Session repository port - interface for session storage."""
+
+from abc import ABC, abstractmethod
+from typing import TypeVar
+
+from ..entities.session import Session
+from ..values.session_id import SessionId
+from ..values.user_id import UserId
+
+PTYHandle = TypeVar("PTYHandle")
+
+
+class SessionRepository[PTYHandle](ABC):
+    """Abstract interface for session storage.
+
+    Infrastructure layer provides concrete implementation.
+    Methods are synchronous - async wrapping is infrastructure concern.
+    """
+
+    @abstractmethod
+    def get(self, session_id: SessionId) -> Session[PTYHandle] | None:
+        """Get session by ID."""
+        ...
+
+    @abstractmethod
+    def get_by_id_str(self, session_id: str) -> Session[PTYHandle] | None:
+        """Get session by ID string (convenience method)."""
+        ...
+
+    @abstractmethod
+    def get_by_user(self, user_id: UserId) -> list[Session[PTYHandle]]:
+        """Get all sessions for a user."""
+        ...
+
+    @abstractmethod
+    def add(self, session: Session[PTYHandle]) -> None:
+        """Add a new session."""
+        ...
+
+    @abstractmethod
+    def remove(self, session_id: SessionId) -> Session[PTYHandle] | None:
+        """Remove and return a session."""
+        ...
+
+    @abstractmethod
+    def count(self) -> int:
+        """Get total session count."""
+        ...
+
+    @abstractmethod
+    def count_for_user(self, user_id: UserId) -> int:
+        """Get session count for a user."""
+        ...
+
+    @abstractmethod
+    def all_sessions(self) -> list[Session[PTYHandle]]:
+        """Get all sessions (for cleanup iteration)."""
+        ...

porterminal/domain/ports/tab_repository.py

@@ -0,0 +1,75 @@
+"""Tab repository port - interface for tab storage."""
+
+from abc import ABC, abstractmethod
+
+from ..entities.tab import Tab
+from ..values.session_id import SessionId
+from ..values.tab_id import TabId
+from ..values.user_id import UserId
+
+
+class TabRepository(ABC):
+    """Abstract interface for tab storage.
+
+    Infrastructure layer provides concrete implementation.
+    Methods are synchronous - async wrapping is infrastructure concern.
+    """
+
+    @abstractmethod
+    def get(self, tab_id: TabId) -> Tab | None:
+        """Get tab by ID."""
+        ...
+
+    @abstractmethod
+    def get_by_id_str(self, tab_id: str) -> Tab | None:
+        """Get tab by ID string (convenience method)."""
+        ...
+
+    @abstractmethod
+    def get_by_user(self, user_id: UserId) -> list[Tab]:
+        """Get all tabs for a user (ordered by last_accessed DESC)."""
+        ...
+
+    @abstractmethod
+    def get_by_session(self, session_id: SessionId) -> list[Tab]:
+        """Get all tabs referencing a specific session."""
+        ...
+
+    @abstractmethod
+    def add(self, tab: Tab) -> None:
+        """Add a new tab."""
+        ...
+
+    @abstractmethod
+    def update(self, tab: Tab) -> None:
+        """Update an existing tab (name, last_accessed)."""
+        ...
+
+    @abstractmethod
+    def remove(self, tab_id: TabId) -> Tab | None:
+        """Remove and return a tab."""
+        ...
+
+    @abstractmethod
+    def remove_by_session(self, session_id: SessionId) -> list[Tab]:
+        """Remove all tabs referencing a session (cascade).
+
+        Returns:
+            List of removed tabs.
+        """
+        ...
+
+    @abstractmethod
+    def count(self) -> int:
+        """Get total tab count."""
+        ...
+
+    @abstractmethod
+    def count_for_user(self, user_id: UserId) -> int:
+        """Get tab count for a user."""
+        ...
+
+    @abstractmethod
+    def all_tabs(self) -> list[Tab]:
+        """Get all tabs (for cleanup iteration)."""
+        ...

porterminal/domain/services/__init__.py

@@ -0,0 +1,18 @@
+"""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
+
+__all__ = [
+    "TokenBucketRateLimiter",
+    "Clock",
+    "EnvironmentSanitizer",
+    "SessionLimitChecker",
+    "SessionLimitConfig",
+    "SessionLimitResult",
+    "TabLimitChecker",
+    "TabLimitConfig",
+    "TabLimitResult",
+]

porterminal/domain/services/environment_sanitizer.py

@@ -0,0 +1,61 @@
+"""Pure environment sanitization service."""
+
+from dataclasses import dataclass
+
+from ..values.environment_rules import EnvironmentRules
+
+
+@dataclass
+class EnvironmentSanitizer:
+    """Pure environment sanitization service.
+
+    Takes environment dict as input (does NOT access os.environ).
+    Infrastructure layer is responsible for providing the input.
+    """
+
+    rules: EnvironmentRules
+
+    def sanitize(self, source_env: dict[str, str]) -> dict[str, str]:
+        """Sanitize environment variables according to rules.
+
+        Args:
+            source_env: Source environment (e.g., from os.environ).
+
+        Returns:
+            Sanitized environment dict.
+        """
+        result: dict[str, str] = {}
+
+        # Copy only allowed variables
+        for var in self.rules.allowed_vars:
+            if var in source_env:
+                result[var] = source_env[var]
+
+        # Defense in depth: remove any blocked vars that might have slipped through
+        for var in self.rules.blocked_vars:
+            result.pop(var, None)
+
+        # Also remove any vars that match blocked patterns
+        blocked_suffixes = ("_KEY", "_SECRET", "_TOKEN", "_PASSWORD", "_CREDENTIAL")
+        for var in list(result.keys()):
+            if any(var.endswith(suffix) for suffix in blocked_suffixes):
+                del result[var]
+
+        # Apply forced variables
+        result.update(self.rules.get_forced_vars_dict())
+
+        return result
+
+    def is_var_allowed(self, var_name: str) -> bool:
+        """Check if a variable name is allowed."""
+        if var_name in self.rules.blocked_vars:
+            return False
+        return var_name in self.rules.allowed_vars
+
+    def is_var_blocked(self, var_name: str) -> bool:
+        """Check if a variable name is blocked."""
+        if var_name in self.rules.blocked_vars:
+            return True
+
+        blocked_suffixes = ("_KEY", "_SECRET", "_TOKEN", "_PASSWORD", "_CREDENTIAL")
+        return any(var_name.endswith(suffix) for suffix in blocked_suffixes)

porterminal/domain/services/rate_limiter.py

@@ -0,0 +1,63 @@
+"""Pure token bucket rate limiter - synchronous, no asyncio dependency."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ..values.rate_limit_config import RateLimitConfig
+
+
+class Clock(Protocol):
+    """Protocol for time source (dependency injection)."""
+
+    def now(self) -> float:
+        """Return current time in seconds (monotonic)."""
+        ...
+
+
+@dataclass
+class TokenBucketRateLimiter:
+    """Pure token bucket rate limiter.
+
+    Synchronous, no asyncio dependency.
+    Time source is injected for testability.
+    """
+
+    config: RateLimitConfig
+    clock: Clock
+    _tokens: float = field(init=False)
+    _last_update: float = field(init=False)
+
+    def __post_init__(self) -> None:
+        self._tokens = float(self.config.burst)
+        self._last_update = self.clock.now()
+
+    def try_acquire(self, tokens: int = 1) -> bool:
+        """Try to acquire tokens.
+
+        Args:
+            tokens: Number of tokens to acquire.
+
+        Returns:
+            True if tokens were acquired, False if rate limited.
+        """
+        now = self.clock.now()
+        elapsed = now - self._last_update
+
+        # Refill bucket
+        self._tokens = min(self.config.burst, self._tokens + elapsed * self.config.rate)
+        self._last_update = now
+
+        if self._tokens >= tokens:
+            self._tokens -= tokens
+            return True
+        return False
+
+    @property
+    def available_tokens(self) -> float:
+        """Get current available tokens (for monitoring)."""
+        return self._tokens
+
+    def reset(self) -> None:
+        """Reset the rate limiter to full capacity."""
+        self._tokens = float(self.config.burst)
+        self._last_update = self.clock.now()

porterminal/domain/services/session_limits.py

@@ -0,0 +1,104 @@
+"""Session limit checking service - pure business logic."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TypeVar
+
+from ..entities.session import (
+    MAX_SESSIONS_PER_USER,
+    MAX_TOTAL_SESSIONS,
+    RECONNECT_WINDOW_SECONDS,
+    SESSION_MAX_DURATION_SECONDS,
+    Session,
+)
+from ..values.user_id import UserId
+
+PTYHandle = TypeVar("PTYHandle")
+
+
+@dataclass(frozen=True)
+class SessionLimitConfig:
+    """Session limit configuration."""
+
+    max_per_user: int = MAX_SESSIONS_PER_USER
+    max_total: int = MAX_TOTAL_SESSIONS
+    max_duration_seconds: int = SESSION_MAX_DURATION_SECONDS
+    reconnect_window_seconds: int = RECONNECT_WINDOW_SECONDS
+
+
+@dataclass
+class SessionLimitResult:
+    """Result of session limit check."""
+
+    allowed: bool
+    reason: str | None = None
+
+
+class SessionLimitChecker:
+    """Check session limits (pure business logic)."""
+
+    def __init__(self, config: SessionLimitConfig | None = None) -> None:
+        self.config = config or SessionLimitConfig()
+
+    def can_create_session(
+        self,
+        user_id: UserId,
+        user_session_count: int,
+        total_session_count: int,
+    ) -> SessionLimitResult:
+        """Check if a new session can be created."""
+        if user_session_count >= self.config.max_per_user:
+            return SessionLimitResult(
+                allowed=False,
+                reason=f"Maximum sessions ({self.config.max_per_user}) reached for user",
+            )
+
+        if total_session_count >= self.config.max_total:
+            return SessionLimitResult(
+                allowed=False,
+                reason="Server session limit reached",
+            )
+
+        return SessionLimitResult(allowed=True)
+
+    def can_reconnect(
+        self,
+        session: Session,
+        requesting_user: UserId,
+    ) -> SessionLimitResult:
+        """Check if user can reconnect to session."""
+        if session.user_id != requesting_user:
+            return SessionLimitResult(
+                allowed=False,
+                reason="Session belongs to another user",
+            )
+        return SessionLimitResult(allowed=True)
+
+    def should_cleanup_session(
+        self,
+        session: Session,
+        now: datetime,
+        is_pty_alive: bool,
+    ) -> tuple[bool, str | None]:
+        """Check if a session should be cleaned up.
+
+        Returns:
+            Tuple of (should_cleanup, reason).
+        """
+        # Primary check: PTY dead = session dead
+        if not is_pty_alive:
+            return True, "PTY died"
+
+        # Check max duration (0 = no limit)
+        if self.config.max_duration_seconds > 0:
+            age = (now - session.created_at).total_seconds()
+            if age > self.config.max_duration_seconds:
+                return True, "Exceeded max duration"
+
+        # Check reconnection window (0 = no limit, only for disconnected sessions)
+        if self.config.reconnect_window_seconds > 0 and not session.is_connected:
+            idle = (now - session.last_activity).total_seconds()
+            if idle > self.config.reconnect_window_seconds:
+                return True, "Reconnection window expired"
+
+        return False, None

porterminal/domain/services/tab_limits.py

@@ -0,0 +1,54 @@
+"""Tab limit checking service - pure business logic."""
+
+from dataclasses import dataclass
+
+from ..entities.tab import MAX_TABS_PER_USER, Tab
+from ..values.user_id import UserId
+
+
+@dataclass(frozen=True)
+class TabLimitConfig:
+    """Tab limit configuration."""
+
+    max_per_user: int = MAX_TABS_PER_USER
+
+
+@dataclass
+class TabLimitResult:
+    """Result of tab limit check."""
+
+    allowed: bool
+    reason: str | None = None
+
+
+class TabLimitChecker:
+    """Check tab limits (pure business logic)."""
+
+    def __init__(self, config: TabLimitConfig | None = None) -> None:
+        self.config = config or TabLimitConfig()
+
+    def can_create_tab(
+        self,
+        user_id: UserId,
+        user_tab_count: int,
+    ) -> TabLimitResult:
+        """Check if a new tab can be created for user."""
+        if user_tab_count >= self.config.max_per_user:
+            return TabLimitResult(
+                allowed=False,
+                reason=f"Maximum tabs ({self.config.max_per_user}) reached",
+            )
+        return TabLimitResult(allowed=True)
+
+    def can_access_tab(
+        self,
+        tab: Tab,
+        requesting_user: UserId,
+    ) -> TabLimitResult:
+        """Check if user can access a tab."""
+        if tab.user_id != requesting_user:
+            return TabLimitResult(
+                allowed=False,
+                reason="Tab belongs to another user",
+            )
+        return TabLimitResult(allowed=True)

porterminal/domain/values/__init__.py

@@ -0,0 +1,25 @@
+"""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
+from .tab_id import TabId
+from .terminal_dimensions import MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS, TerminalDimensions
+from .user_id import UserId
+
+__all__ = [
+    "TerminalDimensions",
+    "MIN_COLS",
+    "MAX_COLS",
+    "MIN_ROWS",
+    "MAX_ROWS",
+    "SessionId",
+    "UserId",
+    "TabId",
+    "ShellCommand",
+    "RateLimitConfig",
+    "EnvironmentRules",
+    "DEFAULT_SAFE_VARS",
+    "DEFAULT_BLOCKED_VARS",
+]

porterminal/domain/values/environment_rules.py

@@ -0,0 +1,156 @@
+"""Environment sanitization rules value object."""
+
+from dataclasses import dataclass, field
+
+# These are the business rules for environment sanitization
+# Extracted from pty/env.py - pure data, no I/O
+
+DEFAULT_SAFE_VARS: frozenset[str] = frozenset(
+    {
+        # System paths
+        "PATH",
+        "PATHEXT",
+        "SYSTEMROOT",
+        "WINDIR",
+        "TEMP",
+        "TMP",
+        "COMSPEC",
+        # User directories
+        "HOME",
+        "USERPROFILE",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "LOCALAPPDATA",
+        "APPDATA",
+        "PROGRAMFILES",
+        "PROGRAMFILES(X86)",
+        "COMMONPROGRAMFILES",
+        # System info
+        "COMPUTERNAME",
+        "USERNAME",
+        "USERDOMAIN",
+        "OS",
+        "PROCESSOR_ARCHITECTURE",
+        "NUMBER_OF_PROCESSORS",
+        # Terminal
+        "TERM",
+        "COLORTERM",
+        "TERM_PROGRAM",
+        # Locale
+        "LANG",
+        "LC_ALL",
+        "LC_CTYPE",
+        # Shell-specific
+        "SHELL",
+        "SHLVL",
+        "PWD",
+        "OLDPWD",
+        # Editor
+        "EDITOR",
+        "VISUAL",
+        # Display (for X11 forwarding if needed)
+        "DISPLAY",
+        # SSH (non-sensitive)
+        "SSH_TTY",
+        "SSH_CONNECTION",
+        # XDG directories
+        "XDG_CONFIG_HOME",
+        "XDG_DATA_HOME",
+        "XDG_CACHE_HOME",
+        "XDG_RUNTIME_DIR",
+        # Python
+        "PYTHONPATH",
+        "VIRTUAL_ENV",
+        # Node
+        "NODE_PATH",
+        # Go
+        "GOPATH",
+        # Rust
+        "CARGO_HOME",
+        "RUSTUP_HOME",
+    }
+)
+
+DEFAULT_BLOCKED_VARS: frozenset[str] = frozenset(
+    {
+        # AWS
+        "AWS_ACCESS_KEY_ID",
+        "AWS_SECRET_ACCESS_KEY",
+        "AWS_SESSION_TOKEN",
+        "AWS_SECURITY_TOKEN",
+        # Azure
+        "AZURE_CLIENT_SECRET",
+        "AZURE_CLIENT_ID",
+        "AZURE_TENANT_ID",
+        # GCP
+        "GOOGLE_APPLICATION_CREDENTIALS",
+        "CLOUDSDK_AUTH_ACCESS_TOKEN",
+        # Git/GitHub/GitLab
+        "GH_TOKEN",
+        "GITHUB_TOKEN",
+        "GITLAB_TOKEN",
+        "GIT_ASKPASS",
+        "GIT_CREDENTIALS",
+        # Package managers
+        "NPM_TOKEN",
+        "PYPI_TOKEN",
+        "RUBYGEMS_API_KEY",
+        # AI APIs
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "GOOGLE_API_KEY",
+        "COHERE_API_KEY",
+        # Payment
+        "STRIPE_SECRET_KEY",
+        "STRIPE_API_KEY",
+        # Database
+        "DATABASE_URL",
+        "DB_PASSWORD",
+        "MYSQL_PASSWORD",
+        "POSTGRES_PASSWORD",
+        "REDIS_PASSWORD",
+        "MONGODB_URI",
+        # Generic secrets
+        "SECRET_KEY",
+        "API_KEY",
+        "API_SECRET",
+        "PRIVATE_KEY",
+        "ACCESS_TOKEN",
+        "REFRESH_TOKEN",
+        "AUTH_TOKEN",
+        "JWT_SECRET",
+        "ENCRYPTION_KEY",
+        # SSH keys (if exposed via env)
+        "SSH_PRIVATE_KEY",
+        "SSH_KEY",
+        # Misc services
+        "SLACK_TOKEN",
+        "DISCORD_TOKEN",
+        "TELEGRAM_TOKEN",
+        "TWILIO_AUTH_TOKEN",
+        "SENDGRID_API_KEY",
+        "MAILGUN_API_KEY",
+    }
+)
+
+
+@dataclass(frozen=True)
+class EnvironmentRules:
+    """Rules for environment variable sanitization."""
+
+    allowed_vars: frozenset[str] = field(default_factory=lambda: DEFAULT_SAFE_VARS)
+    blocked_vars: frozenset[str] = field(default_factory=lambda: DEFAULT_BLOCKED_VARS)
+    forced_vars: tuple[tuple[str, str], ...] = (
+        ("TERM", "xterm-256color"),
+        ("TERM_SESSION_TYPE", "remote-web"),
+    )
+
+    def __post_init__(self) -> None:
+        # Ensure blocked vars are not in allowed vars
+        overlap = self.allowed_vars & self.blocked_vars
+        if overlap:
+            raise ValueError(f"Vars cannot be both allowed and blocked: {overlap}")
+
+    def get_forced_vars_dict(self) -> dict[str, str]:
+        """Get forced variables as a dictionary."""
+        return dict(self.forced_vars)

porterminal/domain/values/rate_limit_config.py

@@ -0,0 +1,21 @@
+"""Rate limit configuration value object."""
+
+from dataclasses import dataclass
+
+# Default business rules
+DEFAULT_RATE = 100.0  # tokens per second
+DEFAULT_BURST = 500
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitConfig:
+    """Rate limiting configuration (value object)."""
+
+    rate: float = DEFAULT_RATE
+    burst: int = DEFAULT_BURST
+
+    def __post_init__(self) -> None:
+        if self.rate <= 0:
+            raise ValueError("Rate must be positive")
+        if self.burst <= 0:
+            raise ValueError("Burst must be positive")

porterminal/domain/values/session_id.py

@@ -0,0 +1,20 @@
+"""Session ID value object."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SessionId:
+    """Strongly-typed session identifier."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value or not isinstance(self.value, str):
+            raise ValueError("SessionId cannot be empty")
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __hash__(self) -> int:
+        return hash(self.value)