putplace 0.4.1__py3-none-any.whl

putplace/__init__.py

@@ -0,0 +1,5 @@
+"""putplace - A Python project."""
+
+from .version import __version__
+
+__all__ = ["__version__"]

putplace/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/config.py

@@ -0,0 +1,167 @@
+"""Application configuration.
+
+Configuration priority (highest to lowest):
+1. Environment variables
+2. ppserver.toml file
+3. Default values
+"""
+
+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. ./ppserver.toml (current directory)
+    2. ~/.config/putplace/ppserver.toml (user config)
+    3. /etc/putplace/ppserver.toml (system config)
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    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"]
+
+        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 (./ppserver.toml, ~/.config/putplace/ppserver.toml, /etc/putplace/ppserver.toml)
+    3. Default values defined below
+    """
+
+    mongodb_url: str = "mongodb://localhost:27017"
+    mongodb_database: str = "putplace"
+    mongodb_collection: str = "file_metadata"
+
+    # API settings
+    api_title: str = "PutPlace API"
+    api_version: str = __version__
+    api_description: str = "File metadata storage API"
+
+    # Storage settings
+    storage_backend: str = "local"  # "local" or "s3"
+    storage_path: str = "/var/putplace/files"  # For local storage
+
+    # 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)
+    # If not specified, boto3 will use standard credential chain:
+    # 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+    # 2. AWS credentials file (~/.aws/credentials)
+    # 3. IAM role (if running on EC2/ECS/Lambda) - RECOMMENDED
+    aws_profile: Optional[str] = None  # Use specific profile from ~/.aws/credentials
+    aws_access_key_id: Optional[str] = None  # NOT RECOMMENDED: use IAM roles or profiles instead
+    aws_secret_access_key: Optional[str] = None  # NOT RECOMMENDED: use IAM roles or profiles instead
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        extra="ignore",  # Ignore extra environment variables (e.g., PUTPLACE_API_KEY for client)
+    )
+
+
+# Load TOML config first, then create Settings (env vars will override)
+_toml_config = load_toml_config()
+settings = Settings(**_toml_config)