neev 0.1.0__py3-none-any.whl

neev/__init__.py

@@ -0,0 +1,6 @@
+from neev.cli import main as cli_main
+
+
+def main() -> None:
+    """Entry point for the neev CLI."""
+    cli_main()

neev/auth.py

@@ -0,0 +1,274 @@
+"""Authentication and session management for neev."""
+
+import base64
+import hmac
+import logging
+import secrets
+import threading
+import time
+
+
+logger = logging.getLogger(__name__)
+
+# Sessions older than this are considered expired and will be pruned.
+TOKEN_TTL = 86400  # 24 hours in seconds
+
+COOKIE_NAME = "neev_session"
+
+# Run opportunistic pruning every Nth validate() call.
+_VALIDATE_PRUNE_INTERVAL = 100
+
+
+# -- Credential validation ---------------------------------------------------
+
+
+def check_basic_auth(
+    authorization_header: str | None,
+    expected_username: str,
+    expected_password: str,
+) -> bool:
+    """Validate a Basic Auth Authorization header against expected credentials.
+
+    Uses ``hmac.compare_digest()`` for constant-time comparison to prevent
+    timing attacks.
+
+    Args:
+        authorization_header: The raw ``Authorization`` header value, or
+            ``None`` if the header was not sent.
+        expected_username: The username to match against.
+        expected_password: The password to match against.
+
+    Returns:
+        ``True`` if credentials match, ``False`` otherwise.
+    """
+    if not authorization_header:
+        return False
+
+    if not authorization_header.startswith("Basic "):
+        return False
+
+    encoded = authorization_header[len("Basic ") :]
+
+    try:
+        decoded = base64.b64decode(encoded).decode("utf-8")
+    except (ValueError, UnicodeDecodeError):
+        logger.debug("Failed to decode Basic Auth credentials")
+        return False
+
+    if ":" not in decoded:
+        return False
+
+    username, password = decoded.split(":", maxsplit=1)
+    return check_credentials(username, password, expected_username, expected_password)
+
+
+def check_credentials(
+    username: str,
+    password: str,
+    expected_username: str,
+    expected_password: str,
+) -> bool:
+    """Validate plaintext credentials against expected values.
+
+    Uses ``hmac.compare_digest()`` for constant-time comparison.
+
+    Args:
+        username: The submitted username.
+        password: The submitted password.
+        expected_username: The username to match against.
+        expected_password: The password to match against.
+
+    Returns:
+        ``True`` if both match, ``False`` otherwise.
+    """
+    username_match = hmac.compare_digest(
+        username.encode("utf-8"), expected_username.encode("utf-8")
+    )
+    password_match = hmac.compare_digest(
+        password.encode("utf-8"), expected_password.encode("utf-8")
+    )
+    return username_match and password_match
+
+
+# -- Session management ------------------------------------------------------
+
+
+class SessionStore:
+    """In-memory session token store with TTL-based expiry.
+
+    Each token is stored alongside its creation timestamp. Expired tokens are
+    pruned on every ``create()`` call. ``validate()`` also rejects tokens that
+    have exceeded ``TOKEN_TTL`` without waiting for the next prune sweep.
+
+    Tokens are generated with ``secrets.token_urlsafe()`` for cryptographic
+    randomness.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty session store."""
+        self._lock = threading.Lock()
+        # Maps token → monotonic creation timestamp.
+        self._tokens: dict[str, float] = {}
+        self._validate_count = 0
+
+    def create(self) -> str:
+        """Create a new session token, pruning expired tokens first.
+
+        Returns:
+            A cryptographically random URL-safe token.
+        """
+        with self._lock:
+            self._prune()
+            token = secrets.token_urlsafe(32)
+            self._tokens[token] = time.monotonic()
+            return token
+
+    def validate(self, token: str) -> bool:
+        """Check whether a session token is valid and unexpired.
+
+        Args:
+            token: The token to validate.
+
+        Returns:
+            ``True`` if the token exists and has not exceeded ``TOKEN_TTL``.
+        """
+        with self._lock:
+            self._validate_count += 1
+            if self._validate_count % _VALIDATE_PRUNE_INTERVAL == 0:
+                self._prune()
+            created_at = self._tokens.get(token)
+            if created_at is None:
+                return False
+            return (time.monotonic() - created_at) < TOKEN_TTL
+
+    def invalidate(self, token: str) -> None:
+        """Remove a session token.
+
+        Args:
+            token: The token to invalidate.
+        """
+        with self._lock:
+            self._tokens.pop(token, None)
+            self._prune()
+
+    def _prune(self) -> None:
+        """Remove all tokens that have exceeded ``TOKEN_TTL``."""
+        now = time.monotonic()
+        expired = [t for t, ts in self._tokens.items() if (now - ts) >= TOKEN_TTL]
+        for token in expired:
+            del self._tokens[token]
+        if expired:
+            logger.debug("Pruned %d expired session token(s)", len(expired))
+
+
+# -- Login rate limiting -----------------------------------------------------
+
+# After this many consecutive failures, start blocking.
+MAX_LOGIN_ATTEMPTS = 5
+
+# Initial cooldown in seconds; doubles on each subsequent failure.
+BASE_COOLDOWN = 30
+
+# Never block longer than this.
+MAX_COOLDOWN = 300
+
+
+class LoginRateLimiter:
+    """Per-IP login rate limiter with exponential backoff.
+
+    Tracks consecutive failed login attempts per client IP. After
+    ``MAX_LOGIN_ATTEMPTS`` failures, further attempts are blocked for a
+    cooldown that doubles with each additional failure, up to
+    ``MAX_COOLDOWN`` seconds.
+
+    Thread-safe — uses the same locking pattern as ``SessionStore``.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty rate limiter."""
+        self._lock = threading.Lock()
+        # Maps IP → (consecutive_failures, last_failure_monotonic).
+        self._attempts: dict[str, tuple[int, float]] = {}
+
+    def is_blocked(self, ip: str) -> bool:
+        """Check whether an IP is currently in a cooldown period.
+
+        Args:
+            ip: The client IP address.
+
+        Returns:
+            ``True`` if the IP must wait before retrying.
+        """
+        with self._lock:
+            record = self._attempts.get(ip)
+            if record is None:
+                return False
+            failures, last_failure = record
+            if failures < MAX_LOGIN_ATTEMPTS:
+                return False
+            cooldown = min(
+                BASE_COOLDOWN * 2 ** (failures - MAX_LOGIN_ATTEMPTS),
+                MAX_COOLDOWN,
+            )
+            return (time.monotonic() - last_failure) < cooldown
+
+    def record_failure(self, ip: str) -> None:
+        """Record a failed login attempt for an IP.
+
+        Args:
+            ip: The client IP address.
+        """
+        now = time.monotonic()
+        with self._lock:
+            self._prune(now)
+            record = self._attempts.get(ip)
+            failures = (record[0] + 1) if record else 1
+            self._attempts[ip] = (failures, now)
+        logger.warning("Failed login attempt %d from %s", failures, ip)
+
+    def _prune(self, now: float) -> None:
+        """Drop entries whose cooldown has fully elapsed.
+
+        Caller must hold ``self._lock``.
+        """
+        expired = [ip for ip, rec in self._attempts.items() if (now - rec[1]) >= MAX_COOLDOWN]
+        for ip in expired:
+            del self._attempts[ip]
+        if expired:
+            logger.debug("Pruned %d stale rate-limit entries", len(expired))
+
+    def record_success(self, ip: str) -> None:
+        """Clear the failure record for an IP after a successful login.
+
+        Args:
+            ip: The client IP address.
+        """
+        with self._lock:
+            self._attempts.pop(ip, None)
+
+
+# -- Cookie helpers ----------------------------------------------------------
+
+
+def parse_cookie(cookie_header: str | None, name: str) -> str | None:
+    """Extract a named value from a Cookie header.
+
+    Args:
+        cookie_header: The raw ``Cookie`` header value, or ``None``.
+        name: The cookie name to look for.
+
+    Returns:
+        The cookie value, or ``None`` if not found.
+    """
+    if not cookie_header:
+        return None
+
+    for raw_pair in cookie_header.split(";"):
+        stripped = raw_pair.strip()
+        if "=" not in stripped:
+            continue
+        key, value = stripped.split("=", maxsplit=1)
+        if key.strip() == name:
+            return value.strip()
+
+    return None

neev/cli.py

@@ -0,0 +1,309 @@
+"""CLI argument parsing and entry point for neev."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from neev.config import Config
+from neev.log import ansi_styled
+from neev.server import run_server
+from neev.toml_config import load_toml, merge_toml_into_args
+
+
+# Real defaults live here (not on the parser). The parser uses ``None`` as a
+# sentinel so CLI-vs-TOML precedence can be resolved unambiguously: if an
+# attribute is ``None`` after parsing, the user did not pass that flag, and
+# TOML (or these defaults) may fill it in.
+_DEFAULTS = {
+    "host": "127.0.0.1",
+    "port": 8000,
+    "show_hidden": False,
+    "enable_zip_download": False,
+    "max_zip_size": 100,
+    "enable_upload": False,
+    "read_only": False,
+}
+
+
+def _print_error(message: str) -> None:
+    """Print a red error message to stderr.
+
+    Args:
+        message: The error description (without ``error:`` prefix).
+    """
+    if sys.stderr.isatty():
+        print(f"\033[31merror:\033[0m {message}", file=sys.stderr)
+    else:
+        print(f"error: {message}", file=sys.stderr)
+
+
+def _on(label: str) -> str:
+    """Format an enabled feature label in green.
+
+    Args:
+        label: The enabled-state text (e.g. ``"enabled"``).
+
+    Returns:
+        Green-styled text.
+    """
+    return ansi_styled(label, "32", stream=sys.stdout)
+
+
+def _off(label: str) -> str:
+    """Format a disabled feature label in dim gray.
+
+    Args:
+        label: The disabled-state text (e.g. ``"disabled"``).
+
+    Returns:
+        Dim-styled text.
+    """
+    return ansi_styled(label, "2", stream=sys.stdout)
+
+
+# -- Parsing and validation ------------------------------------------------
+
+
+def _parse_auth(auth_string: str) -> tuple[str, str]:
+    """Split an ``user:pass`` string into username and password.
+
+    Args:
+        auth_string: Credentials in ``user:pass`` format.
+
+    Returns:
+        A ``(username, password)`` tuple.
+
+    Raises:
+        SystemExit: If the string does not contain exactly one colon.
+    """
+    if ":" not in auth_string:
+        _print_error(f"invalid auth format '{auth_string}' — expected 'user:pass'")
+        raise SystemExit(1)
+    username, password = auth_string.split(":", maxsplit=1)
+    return username, password
+
+
+def _resolve_auth(args: argparse.Namespace) -> tuple[str | None, str | None]:
+    """Resolve auth credentials from CLI flag or environment variable.
+
+    ``--auth`` takes precedence over the ``NEEV_AUTH`` environment variable.
+
+    Args:
+        args: Parsed CLI arguments.
+
+    Returns:
+        A ``(username, password)`` tuple, or ``(None, None)`` if no auth is configured.
+    """
+    auth_string = args.auth or os.environ.get("NEEV_AUTH")
+    if not auth_string:
+        return None, None
+    return _parse_auth(auth_string)
+
+
+def _validate_directory(directory: Path) -> Path:
+    """Resolve and validate the served directory.
+
+    Args:
+        directory: Path provided by the user (may be relative).
+
+    Returns:
+        The resolved absolute path.
+
+    Raises:
+        SystemExit: If the directory does not exist or is not a directory.
+    """
+    resolved = directory.resolve()
+    if not resolved.exists():
+        _print_error(f"directory '{directory}' does not exist")
+        raise SystemExit(1)
+    if not resolved.is_dir():
+        _print_error(f"'{directory}' is not a directory")
+        raise SystemExit(1)
+    return resolved
+
+
+def _validate_port(value: str) -> int:
+    """Validate and convert a port string to an integer.
+
+    Args:
+        value: The raw string from argparse.
+
+    Returns:
+        The port number as an integer.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a valid port (1-65535).
+    """
+    try:
+        port = int(value)
+    except ValueError:
+        msg = f"'{value}' is not a valid port number"
+        raise argparse.ArgumentTypeError(msg) from None
+    if port < 1 or port > 65535:
+        msg = f"port must be between 1 and 65535, got {port}"
+        raise argparse.ArgumentTypeError(msg)
+    return port
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argparse parser with all neev CLI flags.
+
+    All optional flags default to ``None`` so a caller can distinguish "not
+    passed" from "passed with a value that happens to match the default".
+    Real defaults are applied in :func:`build_config` after TOML merging.
+
+    Returns:
+        A configured ``ArgumentParser``.
+    """
+    parser = argparse.ArgumentParser(
+        prog="neev",
+        description="Serve a local directory over HTTP with auth, file browsing, and downloads.",
+    )
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        type=Path,
+        help="directory to serve (default: current directory)",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help="bind address (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        "-p",
+        default=None,
+        type=_validate_port,
+        help="bind port (default: 8000)",
+    )
+    parser.add_argument(
+        "--auth",
+        default=None,
+        help="credentials as 'user:pass' (or set NEEV_AUTH env var)",
+    )
+    parser.add_argument(
+        "--show-hidden",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="show dotfiles, dotdirs, and neev.toml in listings",
+    )
+    parser.add_argument(
+        "--enable-zip-download",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="allow ZIP downloads of folders",
+    )
+    parser.add_argument(
+        "--max-zip-size",
+        default=None,
+        type=int,
+        help="maximum ZIP archive size in MB (default: 100)",
+    )
+    parser.add_argument(
+        "--enable-upload",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="allow file uploads",
+    )
+    parser.add_argument(
+        "--read-only",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="disable all write operations (overrides --enable-upload)",
+    )
+    parser.add_argument(
+        "--banner",
+        default=None,
+        help="message to display at the top of directory listings",
+    )
+    return parser
+
+
+def _print_startup_banner(config: Config) -> None:
+    """Print a human-readable summary of the resolved configuration.
+
+    Args:
+        config: The resolved server configuration.
+    """
+    url = ansi_styled(f"http://{config.host}:{config.port}", "1;36", stream=sys.stdout)
+    directory = ansi_styled(str(config.directory), "1", stream=sys.stdout)
+    serving = ansi_styled("Serving", "1;36", stream=sys.stdout)
+
+    auth_status = _on(f"enabled (user: {config.username})") if config.username else _off("disabled")
+    upload_status = _on("enabled") if config.enable_upload else _off("disabled")
+    zip_status = _on("enabled") if config.enable_zip_download else _off("disabled")
+    hidden_status = _on("visible") if config.show_hidden else _off("hidden")
+
+    print(f"{serving} {directory}")
+    print(f"  {url}")
+    print()
+    print(f"  auth:          {auth_status}")
+    print(f"  uploads:       {upload_status}")
+    print(f"  zip downloads: {zip_status}")
+    print(f"  hidden files:  {hidden_status}")
+    if config.banner:
+        print(f"  banner:        {_on(config.banner)}")
+
+
+def _resolve(args: argparse.Namespace, attr: str) -> Any:
+    """Return ``args.<attr>`` if set, otherwise the registered default."""
+    value = getattr(args, attr)
+    if value is None:
+        return _DEFAULTS[attr]
+    return value
+
+
+def build_config(args: argparse.Namespace, directory: Path) -> Config:
+    """Resolve and validate parsed CLI arguments into a ``Config``.
+
+    Applies real defaults to any attribute still set to ``None`` after TOML
+    merging, handles auth resolution (flag vs env var), and enforces
+    ``--read-only``.
+
+    Args:
+        args: Parsed CLI arguments (post-TOML-merge).
+        directory: The validated, resolved directory to serve.
+
+    Returns:
+        A frozen ``Config`` instance ready for use by the server.
+    """
+    username, password = _resolve_auth(args)
+
+    max_zip_size = _resolve(args, "max_zip_size")
+    if max_zip_size < 1:
+        _print_error("--max-zip-size must be at least 1 MB")
+        raise SystemExit(1)
+
+    enable_upload = _resolve(args, "enable_upload")
+    if _resolve(args, "read_only"):
+        enable_upload = False
+
+    return Config(
+        directory=directory,
+        host=_resolve(args, "host"),
+        port=_resolve(args, "port"),
+        username=username,
+        password=password,
+        show_hidden=_resolve(args, "show_hidden"),
+        enable_zip_download=_resolve(args, "enable_zip_download"),
+        max_zip_size=max_zip_size * 1024 * 1024,
+        enable_upload=enable_upload,
+        banner=args.banner,
+    )
+
+
+def main() -> None:
+    """Entry point for the neev CLI."""
+    parser = _build_parser()
+    args = parser.parse_args()
+    directory = _validate_directory(args.directory)
+    toml_data = load_toml(directory)
+    if toml_data:
+        merge_toml_into_args(args, toml_data)
+    config = build_config(args, directory)
+    _print_startup_banner(config)
+    run_server(config)

neev/config.py

@@ -0,0 +1,52 @@
+"""Configuration dataclass for neev."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Config:
+    """Immutable configuration resolved from CLI arguments and environment.
+
+    All settings are finalized at parse time. For example, ``--read-only``
+    forces ``enable_upload`` to ``False`` before this object is created, so
+    consumers never need to check a separate read-only flag.
+
+    ``__post_init__`` normalizes ``directory`` to its real path (resolving
+    symlinks) and pre-computes ``auth_enabled`` so these are done once at
+    startup, not per-request.
+
+    Attributes:
+        directory: Absolute, realpath-resolved path to the served directory.
+        host: Network address to bind the server to.
+        port: TCP port to listen on.
+        username: HTTP Basic Auth username, or ``None`` if auth is disabled.
+        password: HTTP Basic Auth password, or ``None`` if auth is disabled.
+        show_hidden: Whether dotfiles and dotdirs appear in listings.
+        enable_zip_download: Whether on-the-fly ZIP downloads of folders are allowed.
+        max_zip_size: Maximum size in bytes for generated ZIP archives.
+        enable_upload: Whether file uploads are accepted.
+        auth_enabled: Whether HTTP Basic Auth is active (computed at init).
+    """
+
+    directory: Path
+    host: str
+    port: int
+    username: str | None
+    password: str | None
+    show_hidden: bool
+    enable_zip_download: bool
+    max_zip_size: int
+    enable_upload: bool
+    banner: str | None = None
+    auth_enabled: bool = False
+
+    def __post_init__(self) -> None:
+        """Resolve directory realpath and compute auth_enabled once."""
+        object.__setattr__(self, "directory", Path(os.path.realpath(self.directory)))
+        object.__setattr__(
+            self,
+            "auth_enabled",
+            self.username is not None and self.password is not None,
+        )