putplace-server 0.8.2__py3-none-any.whl

putplace_server/__init__.py

@@ -0,0 +1,5 @@
+"""PutPlace Server - FastAPI server for file metadata storage."""
+
+from .version import __version__
+
+__all__ = ["__version__"]

putplace_server/auth.py

@@ -0,0 +1,279 @@
+"""Authentication and authorization for PutPlace API."""
+
+import hashlib
+import secrets
+from datetime import datetime
+from typing import Optional, TYPE_CHECKING
+
+from fastapi import Depends, HTTPException, Security, status
+from fastapi.security import APIKeyHeader
+from pymongo.asynchronous.collection import AsyncCollection
+
+from . import database
+
+if TYPE_CHECKING:
+    from .database import MongoDB
+
+# API key header name
+API_KEY_HEADER = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+def get_auth_db() -> "MongoDB":
+    """Get database instance for authentication.
+
+    This function is used as a dependency in FastAPI routes.
+    Returns the global database.mongodb instance.
+    """
+    return database.mongodb
+
+
+def generate_api_key() -> str:
+    """Generate a new API key.
+
+    Returns:
+        A cryptographically secure random API key (hex string, 64 characters)
+    """
+    return secrets.token_hex(32)  # 32 bytes = 64 hex characters
+
+
+def hash_api_key(api_key: str) -> str:
+    """Hash an API key for secure storage.
+
+    Args:
+        api_key: The API key to hash
+
+    Returns:
+        SHA256 hash of the API key
+    """
+    return hashlib.sha256(api_key.encode()).hexdigest()
+
+
+class APIKeyAuth:
+    """API Key authentication manager."""
+
+    def __init__(self, db: database.MongoDB):
+        """Initialize API key authentication.
+
+        Args:
+            db: MongoDB database instance
+        """
+        self.db = db
+
+    async def get_api_keys_collection(self) -> AsyncCollection:
+        """Get the API keys collection.
+
+        Returns:
+            MongoDB collection for API keys
+        """
+        if self.db.client is None:
+            raise RuntimeError("Database not connected")
+
+        db = self.db.client[self.db.collection.database.name]
+        return db["api_keys"]
+
+    async def create_api_key(
+        self,
+        name: str,
+        user_id: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> tuple[str, dict]:
+        """Create a new API key.
+
+        Args:
+            name: Name/identifier for this API key
+            user_id: Optional user ID who owns this key
+            description: Optional description
+
+        Returns:
+            Tuple of (api_key, key_metadata)
+            The api_key is returned only once and should be given to the user.
+            The key_metadata contains the stored information (without the actual key).
+
+        Raises:
+            RuntimeError: If database not connected
+        """
+        collection = await self.get_api_keys_collection()
+
+        # Generate new API key
+        api_key = generate_api_key()
+        key_hash = hash_api_key(api_key)
+
+        # Create metadata document
+        key_doc = {
+            "key_hash": key_hash,
+            "name": name,
+            "description": description,
+            "user_id": user_id,  # Associate with user
+            "created_at": datetime.utcnow(),
+            "last_used_at": None,
+            "is_active": True,
+        }
+
+        # Insert into database
+        result = await collection.insert_one(key_doc.copy())
+
+        # Return the plain API key (only time we show it) and metadata
+        key_doc["_id"] = str(result.inserted_id)
+        key_doc.pop("key_hash")  # Don't include hash in response
+
+        return api_key, key_doc
+
+    async def verify_api_key(self, api_key: str) -> Optional[dict]:
+        """Verify an API key and return its metadata.
+
+        Args:
+            api_key: The API key to verify
+
+        Returns:
+            Key metadata if valid and active, None otherwise
+        """
+        collection = await self.get_api_keys_collection()
+
+        # Hash the provided key
+        key_hash = hash_api_key(api_key)
+
+        # Look up in database
+        key_doc = await collection.find_one({
+            "key_hash": key_hash,
+            "is_active": True,
+        })
+
+        if key_doc:
+            # Update last used timestamp
+            await collection.update_one(
+                {"_id": key_doc["_id"]},
+                {"$set": {"last_used_at": datetime.utcnow()}}
+            )
+
+            # Return metadata (without hash)
+            key_doc.pop("key_hash", None)
+            key_doc["_id"] = str(key_doc["_id"])
+            return key_doc
+
+        return None
+
+    async def revoke_api_key(self, key_id: str) -> bool:
+        """Revoke (deactivate) an API key.
+
+        Args:
+            key_id: MongoDB ObjectId of the key to revoke
+
+        Returns:
+            True if key was revoked, False if not found
+        """
+        from bson import ObjectId
+
+        collection = await self.get_api_keys_collection()
+
+        result = await collection.update_one(
+            {"_id": ObjectId(key_id)},
+            {"$set": {"is_active": False}}
+        )
+
+        return result.modified_count > 0
+
+    async def list_api_keys(self, user_id: Optional[str] = None) -> list[dict]:
+        """List all API keys (without showing actual keys).
+
+        Args:
+            user_id: Optional user ID to filter keys by owner
+
+        Returns:
+            List of API key metadata
+        """
+        collection = await self.get_api_keys_collection()
+
+        # Build query filter
+        query = {}
+        if user_id:
+            query["user_id"] = user_id
+
+        cursor = collection.find(query, {"key_hash": 0})
+        keys = []
+
+        async for key_doc in cursor:
+            key_doc["_id"] = str(key_doc["_id"])
+            keys.append(key_doc)
+
+        return keys
+
+    async def delete_api_key(self, key_id: str) -> bool:
+        """Permanently delete an API key.
+
+        Args:
+            key_id: MongoDB ObjectId of the key to delete
+
+        Returns:
+            True if key was deleted, False if not found
+        """
+        from bson import ObjectId
+
+        collection = await self.get_api_keys_collection()
+
+        result = await collection.delete_one({"_id": ObjectId(key_id)})
+
+        return result.deleted_count > 0
+
+
+# Dependency for protected endpoints
+async def get_current_api_key(
+    api_key: str = Security(API_KEY_HEADER),
+    db: "MongoDB" = Depends(get_auth_db),
+) -> dict:
+    """FastAPI dependency to validate API key.
+
+    Args:
+        api_key: API key from request header
+        db: Database instance (injected)
+
+    Returns:
+        API key metadata if valid
+
+    Raises:
+        HTTPException: If API key is missing or invalid
+    """
+    if not api_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="API key required. Include X-API-Key header.",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+    # Get API key authenticator
+    auth = APIKeyAuth(db)
+
+    # Verify the key
+    key_metadata = await auth.verify_api_key(api_key)
+
+    if not key_metadata:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or inactive API key",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+    return key_metadata
+
+
+# Optional dependency - allows unauthenticated access
+async def get_optional_api_key(
+    api_key: str = Security(API_KEY_HEADER),
+    db: "MongoDB" = Depends(get_auth_db),
+) -> Optional[dict]:
+    """FastAPI dependency for optional API key authentication.
+
+    Returns API key metadata if provided and valid, None otherwise.
+    Does not raise an error if no key is provided.
+
+    Args:
+        api_key: API key from request header
+        db: Database instance (injected)
+
+    Returns:
+        API key metadata if valid, None if not provided or invalid
+    """
+    if not api_key:
+        return None
+
+    auth = APIKeyAuth(db)
+    return await auth.verify_api_key(api_key)

putplace_server/cleanup_tasks.py

@@ -0,0 +1,42 @@
+"""Background cleanup tasks for expired pending users."""
+
+import asyncio
+import logging
+from datetime import datetime
+
+from .database import mongodb
+
+logger = logging.getLogger(__name__)
+
+
+async def cleanup_expired_pending_users_task():
+    """
+    Periodically clean up expired pending users.
+
+    Runs every hour and deletes pending users whose confirmation has expired.
+    """
+    while True:
+        try:
+            # Wait 1 hour between cleanup runs
+            await asyncio.sleep(3600)  # 3600 seconds = 1 hour
+
+            logger.info("Running cleanup task for expired pending users...")
+
+            # Delete expired pending users
+            deleted_count = await mongodb.cleanup_expired_pending_users()
+
+            if deleted_count > 0:
+                logger.info(f"Cleaned up {deleted_count} expired pending user(s)")
+            else:
+                logger.debug("No expired pending users to clean up")
+
+        except Exception as e:
+            logger.error(f"Error in cleanup task: {e}")
+            # Continue running even if there's an error
+            continue
+
+
+def start_cleanup_task():
+    """Start the cleanup background task."""
+    asyncio.create_task(cleanup_expired_pending_users_task())
+    logger.info("Started background cleanup task for expired pending users")

putplace_server/config.py

@@ -0,0 +1,273 @@
+"""Application configuration.
+
+Configuration priority (highest to lowest):
+1. Environment variables
+2. ppserver.toml file
+3. Default values
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .version import __version__
+
+# Import tomli for Python < 3.11, tomllib for Python >= 3.11
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None  # type: ignore
+
+
+def find_config_file() -> Optional[Path]:
+    """Find ppserver.toml file in standard locations.
+
+    Search order:
+    1. PUTPLACE_CONFIG environment variable (if set)
+    2. ./ppserver.toml (current directory)
+    3. ~/.config/putplace/ppserver.toml (user config)
+    4. /etc/putplace/ppserver.toml (system config)
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    # Check environment variable first
+    env_config = os.environ.get("PUTPLACE_CONFIG")
+    if env_config:
+        env_path = Path(env_config)
+        if env_path.exists() and env_path.is_file():
+            return env_path
+        # If PUTPLACE_CONFIG is set but file doesn't exist, log warning but continue searching
+        import logging
+        logging.warning(f"PUTPLACE_CONFIG set to {env_config} but file not found, searching standard locations")
+
+    search_paths = [
+        Path.cwd() / "ppserver.toml",
+        Path.home() / ".config" / "putplace" / "ppserver.toml",
+        Path("/etc/putplace/ppserver.toml"),
+    ]
+
+    for path in search_paths:
+        if path.exists() and path.is_file():
+            return path
+
+    return None
+
+
+def load_toml_config() -> dict[str, Any]:
+    """Load configuration from TOML file.
+
+    Returns:
+        Dictionary with configuration values, empty dict if no config file found
+    """
+    if tomllib is None:
+        return {}
+
+    config_file = find_config_file()
+    if config_file is None:
+        return {}
+
+    try:
+        with open(config_file, "rb") as f:
+            toml_data = tomllib.load(f)
+
+        # Flatten nested TOML structure to match Settings field names
+        config = {}
+
+        # Database settings
+        if "database" in toml_data:
+            db = toml_data["database"]
+            if "mongodb_url" in db:
+                config["mongodb_url"] = db["mongodb_url"]
+            if "mongodb_database" in db:
+                config["mongodb_database"] = db["mongodb_database"]
+            if "mongodb_collection" in db:
+                config["mongodb_collection"] = db["mongodb_collection"]
+
+        # API settings
+        if "api" in toml_data:
+            api = toml_data["api"]
+            if "title" in api:
+                config["api_title"] = api["title"]
+            if "description" in api:
+                config["api_description"] = api["description"]
+
+        # Storage settings
+        if "storage" in toml_data:
+            storage = toml_data["storage"]
+            if "backend" in storage:
+                config["storage_backend"] = storage["backend"]
+            if "path" in storage:
+                config["storage_path"] = storage["path"]
+            if "s3_bucket_name" in storage:
+                config["s3_bucket_name"] = storage["s3_bucket_name"]
+            if "s3_region_name" in storage:
+                config["s3_region_name"] = storage["s3_region_name"]
+            if "s3_prefix" in storage:
+                config["s3_prefix"] = storage["s3_prefix"]
+
+        # AWS settings
+        if "aws" in toml_data:
+            aws = toml_data["aws"]
+            if "profile" in aws:
+                config["aws_profile"] = aws["profile"]
+            if "access_key_id" in aws:
+                config["aws_access_key_id"] = aws["access_key_id"]
+            if "secret_access_key" in aws:
+                config["aws_secret_access_key"] = aws["secret_access_key"]
+
+        # OAuth settings
+        if "oauth" in toml_data:
+            oauth = toml_data["oauth"]
+            if "google_client_id" in oauth:
+                config["google_client_id"] = oauth["google_client_id"]
+            if "google_client_secret" in oauth:
+                config["google_client_secret"] = oauth["google_client_secret"]
+
+        # Email settings
+        if "email" in toml_data:
+            email = toml_data["email"]
+            if "sender_email" in email:
+                config["sender_email"] = email["sender_email"]
+            if "base_url" in email:
+                config["base_url"] = email["base_url"]
+            if "aws_region" in email:
+                config["email_aws_region"] = email["aws_region"]
+
+        # Server settings
+        if "server" in toml_data:
+            server = toml_data["server"]
+            if "registration_enabled" in server:
+                config["registration_enabled"] = server["registration_enabled"]
+
+        return config
+
+    except Exception as e:
+        # If there's an error reading TOML, just return empty config
+        # Environment variables and defaults will still work
+        import logging
+        logging.warning(f"Failed to load TOML config from {config_file}: {e}")
+        return {}
+
+
+class Settings(BaseSettings):
+    """Application settings.
+
+    Configuration is loaded in this priority order (highest to lowest):
+    1. Environment variables (e.g., MONGODB_URL, STORAGE_BACKEND)
+    2. ppserver.toml file (search order below)
+    3. Default values defined below
+
+    Config file search order (PUTPLACE_CONFIG overrides):
+    - PUTPLACE_CONFIG environment variable (if set, takes highest priority)
+    - ./ppserver.toml (current directory)
+    - ~/.config/putplace/ppserver.toml (user config)
+    - /etc/putplace/ppserver.toml (system config)
+    """
+
+    mongodb_url: str
+    mongodb_database: str
+    mongodb_collection: str
+
+    # API settings
+    api_title: str
+    api_version: str = __version__
+    api_description: str
+
+    # Storage settings
+    storage_backend: str
+    storage_path: str
+
+    # S3 storage settings (only used if storage_backend="s3")
+    s3_bucket_name: Optional[str] = None
+    s3_region_name: str = "us-east-1"
+    s3_prefix: str = "files/"
+
+    # AWS credentials (OPTIONAL - see SECURITY.md for best practices)
+    aws_profile: Optional[str] = None
+    aws_access_key_id: Optional[str] = None
+    aws_secret_access_key: Optional[str] = None
+
+    # OAuth settings
+    google_client_id: Optional[str] = None
+    google_client_secret: Optional[str] = None
+
+    # Email settings for SES
+    sender_email: str = "noreply@putplace.org"
+    base_url: str = "http://localhost:8000"
+    email_aws_region: str = "eu-west-1"
+
+    # Registration control
+    registration_enabled: bool = True  # Set to False to disable new user registration
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        extra="ignore",  # Ignore extra environment variables (e.g., PUTPLACE_API_KEY for client)
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize settings with priority: env vars > TOML > defaults."""
+        # Load TOML config
+        toml_config = load_toml_config()
+
+        # Helper to get value with priority: explicit kwarg > env var > TOML > default
+        def get_value(key: str, default: Any = None) -> Any:
+            # 1. Check if explicitly passed as kwarg
+            if key in kwargs:
+                return kwargs[key]
+            # 2. Check environment variable (uppercase)
+            env_val = os.getenv(key.upper())
+            if env_val is not None:
+                return env_val
+            # 3. Check TOML config
+            if key in toml_config:
+                return toml_config[key]
+            # 4. Use default
+            return default
+
+        # Build values dict with proper priority
+        values = {
+            "mongodb_url": get_value("mongodb_url", "mongodb://localhost:27017"),
+            "mongodb_database": get_value("mongodb_database", "putplace"),
+            "mongodb_collection": get_value("mongodb_collection", "file_metadata"),
+            "api_title": get_value("api_title", "PutPlace API"),
+            "api_description": get_value("api_description", "File metadata storage API"),
+            "storage_backend": get_value("storage_backend", "local"),
+            "storage_path": get_value("storage_path", "/var/putplace/files"),
+            "s3_bucket_name": get_value("s3_bucket_name"),
+            "s3_region_name": get_value("s3_region_name", "us-east-1"),
+            "s3_prefix": get_value("s3_prefix", "files/"),
+            "aws_profile": get_value("aws_profile"),
+            "aws_access_key_id": get_value("aws_access_key_id"),
+            "aws_secret_access_key": get_value("aws_secret_access_key"),
+            "google_client_id": get_value("google_client_id"),
+            "google_client_secret": get_value("google_client_secret"),
+            "sender_email": get_value("sender_email", "noreply@putplace.org"),
+            "base_url": get_value("base_url", "http://localhost:8000"),
+            "email_aws_region": get_value("email_aws_region", "eu-west-1"),
+        }
+
+        # Merge with any remaining kwargs
+        values.update({k: v for k, v in kwargs.items() if k not in values})
+
+        super().__init__(**values)
+
+
+# Create settings instance
+# Pydantic Settings priority (highest to lowest):
+# 1. Constructor arguments (not used here)
+# 2. Environment variables
+# 3. Defaults in class definition
+# Since we're not passing any constructor args, env vars will naturally override defaults
+settings = Settings()
+
+
+def get_settings() -> Settings:
+    """Get application settings."""
+    return settings