codeframe-ai 0.9.0__py3-none-any.whl

codeframe/auth/dependencies.py

@@ -0,0 +1,358 @@
+"""Authentication dependencies for route handlers.
+
+Supports dual authentication:
+- JWT Bearer tokens (existing FastAPI Users integration)
+- API keys via X-API-Key header (new for programmatic access)
+
+API keys use scope-based permissions (read, write, admin).
+JWT tokens get full permissions for backward compatibility.
+"""
+
+import logging
+import os
+import re
+from typing import Callable, Dict, Optional, Any
+
+from fastapi import Depends, HTTPException, Request, Security, status
+from fastapi.security import APIKeyHeader, HTTPBearer, HTTPAuthorizationCredentials
+
+from codeframe.auth.models import User
+from codeframe.auth.api_keys import (
+    extract_prefix,
+    verify_api_key,
+    SCOPE_READ,
+    SCOPE_WRITE,
+    SCOPE_ADMIN,
+)
+from codeframe.auth.scopes import has_scope
+
+logger = logging.getLogger(__name__)
+
+# Security schemes
+security = HTTPBearer(auto_error=False)
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+# Truthy/falsy values for CODEFRAME_AUTH_REQUIRED (case-insensitive).
+_AUTH_FALSY = {"0", "false", "no", "off"}
+
+# Routes allowed to authenticate via a ?token=<JWT> query parameter. Browser
+# EventSource (SSE) cannot send an Authorization header, so these streaming
+# routes accept the token in the URL — the same trade-off the WebSocket
+# routes already make. Keep this list tight: query-string credentials can
+# leak via proxy/access logs and browser history, so the fallback must NOT
+# apply to the rest of the API (codex review P2, issue #336).
+_QUERY_TOKEN_PATHS = (
+    re.compile(r"^/api/v2/tasks/[^/]+/stream$"),  # task event stream (SSE)
+    re.compile(r"^/api/v2/prd/stress-test$"),  # PRD stress-test stream (SSE)
+)
+
+
+def _query_token_allowed(path: str) -> bool:
+    """Whether this request path may authenticate via ?token= (SSE only)."""
+    return any(pattern.match(path) for pattern in _QUERY_TOKEN_PATHS)
+
+
+def auth_required() -> bool:
+    """Whether authentication is enforced, read from the environment.
+
+    Controlled by ``CODEFRAME_AUTH_REQUIRED`` (default ON / secure by default).
+    Read at request time so tests can monkeypatch the value per call.
+
+    Falsy values (case-insensitive): ``0``, ``false``, ``no``, ``off``.
+    Anything else (including unset) is treated as enabled.
+    """
+    value = os.getenv("CODEFRAME_AUTH_REQUIRED")
+    if value is None:
+        return True
+    return value.strip().lower() not in _AUTH_FALSY
+
+
+async def get_current_user(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+) -> User:
+    """Get currently authenticated user.
+
+    Requires a valid JWT, supplied as an ``Authorization: Bearer`` header.
+    On the allowlisted SSE routes only (``_QUERY_TOKEN_PATHS``), a
+    ``?token=<JWT>`` query parameter is accepted when no header is present
+    (browser EventSource cannot send headers; mirrors the WebSocket
+    auth pattern).
+
+    Args:
+        request: FastAPI request object
+        credentials: Bearer token from Authorization header (optional)
+
+    Returns:
+        Authenticated user
+
+    Raises:
+        HTTPException: 401 if authentication not provided or invalid
+    """
+    # Resolve the bearer token from the Authorization header. Only the
+    # allowlisted SSE routes may fall back to a ?token= query parameter
+    # (EventSource cannot send headers); everywhere else query-string
+    # credentials are rejected to keep them out of logs/history.
+    token: Optional[str] = None
+    if credentials and getattr(credentials, "credentials", None):
+        token = credentials.credentials
+    elif request is not None and _query_token_allowed(request.url.path):
+        token = request.query_params.get("token")
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Validate JWT token
+    try:
+        import jwt as pyjwt
+        from codeframe.auth.manager import (
+            SECRET,
+            JWT_ALGORITHM,
+            JWT_AUDIENCE,
+            get_async_session_maker,
+        )
+        from sqlalchemy import select
+
+        # Decode JWT token directly using PyJWT
+        # Note: We use direct PyJWT decoding instead of JWTStrategy.read_token()
+        # because read_token() requires a user_manager instance, which would
+        # create a circular dependency. The JWT constants are centralized in
+        # auth.manager to ensure consistency with the JWTStrategy configuration.
+        try:
+            payload = pyjwt.decode(
+                token,
+                SECRET,
+                algorithms=[JWT_ALGORITHM],
+                audience=JWT_AUDIENCE,
+            )
+            user_id_str = payload.get("sub")
+            if not user_id_str:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Invalid token: missing subject",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            user_id = int(user_id_str)
+        except pyjwt.ExpiredSignatureError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token expired",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        except (pyjwt.InvalidTokenError, ValueError) as e:
+            logger.debug(f"JWT decode error: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        # Get user from database
+        async_session_maker = get_async_session_maker()
+        async with async_session_maker() as session:
+            result = await session.execute(select(User).where(User.id == user_id))
+            user = result.scalar_one_or_none()
+
+            if user is None:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="User not found",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+
+            if not user.is_active:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="User is inactive",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+
+            return user
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        # Log full error server-side for debugging
+        logger.error(f"Authentication error: {str(e)}", exc_info=True)
+        # Return generic message to client (avoid leaking implementation details)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication failed",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_current_user_optional(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+) -> Optional[User]:
+    """Get currently authenticated user, or None if not authenticated.
+
+    Non-raising version for endpoints that optionally use authentication.
+    """
+    try:
+        return await get_current_user(request, credentials)
+    except HTTPException:
+        return None
+
+
+# =============================================================================
+# API Key Authentication
+# =============================================================================
+
+
+async def get_api_key_auth(
+    api_key: Optional[str] = Security(api_key_header),
+    request: Request = None,
+) -> Optional[Dict[str, Any]]:
+    """Extract and validate API key from X-API-Key header.
+
+    Args:
+        api_key: API key from header (auto-extracted by FastAPI Security)
+        request: FastAPI request object (for accessing db via state)
+
+    Returns:
+        Auth dict if valid API key, None otherwise.
+        Dict contains: type, user_id, scopes, key_id
+    """
+    if not api_key:
+        return None
+
+    try:
+        # Get database from app state (singleton) or request state
+        db = getattr(request.app.state, "db", None)
+        if db is None:
+            db = getattr(request.state, "db", None)
+        if db is None:
+            # Fallback: create database connection
+            logger.warning("No db in app.state, creating fallback connection for API key auth")
+            import os
+            from codeframe.platform_store.database import Database
+
+            db_path = os.getenv(
+                "DATABASE_PATH",
+                os.path.join(os.getcwd(), ".codeframe", "state.db")
+            )
+            db = Database(db_path)
+            db.initialize()
+            # Store on request state so it can be cleaned up by middleware
+            if request is not None:
+                request.state.db = db
+
+        # Extract prefix and look up key
+        try:
+            prefix = extract_prefix(api_key)
+        except ValueError:
+            logger.warning("API key auth failed: invalid key format")
+            return None
+
+        key_record = db.api_keys.get_by_prefix(prefix)
+        if key_record is None:
+            logger.warning(f"API key auth failed: key not found (prefix: {prefix[:4]}...)")
+            return None
+
+        # Verify the full key against stored hash
+        if not verify_api_key(api_key, key_record["key_hash"]):
+            logger.warning(f"API key auth failed: verification failed (prefix: {prefix[:4]}...)")
+            return None
+
+        # Update last used timestamp (fire and forget)
+        try:
+            db.api_keys.update_last_used(key_record["id"])
+        except Exception as e:
+            logger.warning(f"Failed to update last_used_at: {e}")
+
+        return {
+            "type": "api_key",
+            "user_id": key_record["user_id"],
+            "scopes": key_record["scopes"],
+            "key_id": key_record["id"],
+        }
+
+    except Exception as e:
+        logger.debug(f"API key authentication error: {e}")
+        return None
+
+
+async def require_auth(
+    api_key_auth: Optional[Dict[str, Any]] = Depends(get_api_key_auth),
+    jwt_user: Optional[User] = Depends(get_current_user_optional),
+) -> Dict[str, Any]:
+    """Require authentication via either API key or JWT token.
+
+    API keys take precedence if both are present.
+
+    Args:
+        api_key_auth: Result from get_api_key_auth (if API key provided)
+        jwt_user: Result from get_current_user_optional (if JWT provided)
+
+    Returns:
+        Auth dict with: type, user_id, scopes, and optional user/key_id
+
+    Raises:
+        HTTPException: 401 if no valid authentication provided
+    """
+    # Prefer API key if provided
+    if api_key_auth is not None:
+        return api_key_auth
+
+    # Fall back to JWT
+    if jwt_user is not None:
+        return {
+            "type": "jwt",
+            "user_id": jwt_user.id,
+            # JWT users get all scopes for backward compatibility
+            "scopes": [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN],
+            "user": jwt_user,
+        }
+
+    # Auth disabled (local opt-out): return a synthetic local-admin principal
+    # instead of raising. Real credentials above always take precedence.
+    if not auth_required():
+        return {
+            "type": "disabled",
+            "user_id": None,
+            "scopes": [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN],
+        }
+
+    # No authentication provided
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Authentication required",
+        headers={"WWW-Authenticate": "Bearer, ApiKey"},
+    )
+
+
+def require_scope(required_scope: str) -> Callable:
+    """Create a dependency that checks for a required scope.
+
+    Scope Hierarchy:
+        - admin: grants read, write, and admin permissions
+        - write: grants read and write permissions
+        - read: grants read permission only
+
+    Usage:
+        @router.post("/resource")
+        async def create_resource(auth: dict = Depends(require_scope("write"))):
+            ...
+
+    Args:
+        required_scope: The scope required for access (read, write, or admin)
+
+    Returns:
+        Dependency function that validates scope
+    """
+    async def check_scope(auth: Dict[str, Any] = Depends(require_auth)) -> Dict[str, Any]:
+        """Verify principal has required scope."""
+        if not has_scope(auth, required_scope):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Insufficient permissions: '{required_scope}' scope required",
+            )
+        return auth
+
+    return check_scope

codeframe/auth/manager.py

@@ -0,0 +1,178 @@
+"""User manager and authentication backends."""
+import logging
+import os
+from typing import AsyncGenerator, Optional
+
+from fastapi import Depends, Request
+from fastapi_users import BaseUserManager, IntegerIDMixin, FastAPIUsers
+from fastapi_users.authentication import (
+    AuthenticationBackend,
+    BearerTransport,
+    JWTStrategy,
+)
+from fastapi_users.db import SQLAlchemyUserDatabase
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+
+from codeframe.auth.models import User
+
+logger = logging.getLogger(__name__)
+
+# Get configuration from environment
+DEFAULT_SECRET = "CHANGE-ME-IN-PRODUCTION"
+SECRET = os.getenv("AUTH_SECRET", DEFAULT_SECRET)
+
+# JWT configuration constants
+# These must match the JWTStrategy defaults from FastAPI Users
+JWT_ALGORITHM = "HS256"
+JWT_AUDIENCE = ["fastapi-users:auth"]
+JWT_LIFETIME_SECONDS = int(os.getenv("JWT_LIFETIME_SECONDS", "604800"))  # 7 days
+
+# Warn if using default secret (but allow for development)
+if SECRET == DEFAULT_SECRET:
+    logger.warning(
+        "⚠️  AUTH_SECRET not set - using default value. "
+        "DO NOT USE IN PRODUCTION! Set AUTH_SECRET environment variable."
+    )
+
+# Create async SQLAlchemy engine for auth
+# Uses aiosqlite driver for async SQLite access
+_engine = None
+_async_session_maker = None
+_current_database_path = None
+
+
+def _get_database_path() -> str:
+    """Get the current database path from environment."""
+    return os.getenv(
+        "DATABASE_PATH",
+        os.path.join(os.getcwd(), ".codeframe", "state.db")
+    )
+
+
+def reset_auth_engine():
+    """Reset the async SQLAlchemy engine.
+
+    Call this when DATABASE_PATH environment variable changes
+    (e.g., in tests that use temporary databases).
+
+    Also disposes of the engine to close all connections.
+    """
+    global _engine, _async_session_maker, _current_database_path
+
+    # Dispose of engine to close all connections
+    if _engine is not None:
+        import asyncio
+        try:
+            # Try to dispose synchronously if possible
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # Can't await in running loop, schedule for later
+                asyncio.ensure_future(_engine.dispose())
+            else:
+                loop.run_until_complete(_engine.dispose())
+        except RuntimeError:
+            # No event loop available, create one temporarily
+            asyncio.run(_engine.dispose())
+        except Exception:
+            # Ignore disposal errors during cleanup
+            pass
+
+    _engine = None
+    _async_session_maker = None
+    _current_database_path = None
+
+
+def get_engine():
+    """Get or create the async SQLAlchemy engine."""
+    global _engine, _current_database_path
+
+    # Get current database path
+    database_path = _get_database_path()
+
+    # If path changed, reset engine
+    if _current_database_path is not None and _current_database_path != database_path:
+        reset_auth_engine()
+
+    if _engine is None:
+        # Use aiosqlite for async SQLite support
+        database_url = f"sqlite+aiosqlite:///{database_path}"
+        _engine = create_async_engine(database_url, echo=False)
+        _current_database_path = database_path
+    return _engine
+
+
+def get_async_session_maker():
+    """Get or create the async session maker."""
+    global _async_session_maker
+    if _async_session_maker is None:
+        _async_session_maker = async_sessionmaker(
+            get_engine(),
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+    return _async_session_maker
+
+
+class UserManager(IntegerIDMixin, BaseUserManager[User, int]):
+    """User manager for CodeFRAME."""
+
+    reset_password_token_secret = SECRET
+    verification_token_secret = SECRET
+
+    async def on_after_register(self, user: User, request: Optional[Request] = None):
+        """Called after successful registration."""
+        logger.info(
+            "User registered",
+            extra={"user_id": user.id, "email": user.email}
+        )
+
+    async def on_after_login(
+        self, user: User, request: Optional[Request] = None, response=None
+    ):
+        """Called after successful login."""
+        # Only log user_id on login (avoid excessive email logging)
+        logger.info("User logged in", extra={"user_id": user.id})
+
+
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    """Get async database session for auth."""
+    async_session_maker = get_async_session_maker()
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    """Get user database adapter."""
+    yield SQLAlchemyUserDatabase(session, User)
+
+
+async def get_user_manager(user_db: SQLAlchemyUserDatabase = Depends(get_user_db)):
+    """Get user manager."""
+    yield UserManager(user_db)
+
+
+# JWT Bearer token transport
+bearer_transport = BearerTransport(tokenUrl="auth/jwt/login")
+
+
+def get_jwt_strategy() -> JWTStrategy:
+    """JWT strategy for authentication."""
+    return JWTStrategy(secret=SECRET, lifetime_seconds=JWT_LIFETIME_SECONDS)
+
+
+# Authentication backend
+auth_backend = AuthenticationBackend(
+    name="jwt",
+    transport=bearer_transport,
+    get_strategy=get_jwt_strategy,
+)
+
+# FastAPIUsers instance
+fastapi_users = FastAPIUsers[User, int](
+    get_user_manager,
+    [auth_backend],
+)
+
+# Dependencies for protected routes
+current_active_user = fastapi_users.current_user(active=True)
+current_superuser = fastapi_users.current_user(active=True, superuser=True)

codeframe/auth/models.py

@@ -0,0 +1,30 @@
+"""SQLAlchemy User model for fastapi-users."""
+from typing import Optional
+from fastapi_users.db import SQLAlchemyBaseUserTable
+from sqlalchemy import Integer, String, Boolean
+from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase
+
+class Base(DeclarativeBase):
+    """SQLAlchemy declarative base."""
+    pass
+
+class User(SQLAlchemyBaseUserTable[int], Base):
+    """User model compatible with existing users table.
+    
+    Uses integer primary key instead of UUID to match existing schema.
+    Maps to existing 'users' table created by SchemaManager.
+    """
+    __tablename__ = "users"
+    
+    # Override id to use Integer instead of UUID
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    
+    # Required fastapi-users fields (already in schema)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String(1024), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    is_verified: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    
+    # Additional fields from existing schema
+    name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)

codeframe/auth/router.py

@@ -0,0 +1,93 @@
+"""Auth router configuration."""
+import asyncio
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import func, select
+
+from codeframe.auth.schemas import UserCreate, UserRead, UserUpdate
+from codeframe.auth.manager import auth_backend, fastapi_users, get_async_session_maker
+from codeframe.auth.models import User
+from codeframe.auth.api_key_router import router as api_key_router
+
+router = APIRouter()
+
+
+# Placeholder password for the seeded bootstrap admin (id=1). It cannot match
+# any bcrypt hash, so that account can never log in. It is therefore NOT a real
+# account and does not close the registration window. See SchemaManager
+# ._ensure_default_admin_user.
+_DISABLED_PASSWORD = "!DISABLED!"
+
+# Serializes the bootstrap registration check-then-create window. The count
+# check (here) and the user INSERT (fastapi-users route handler) run in
+# separate transactions, so without the lock two concurrent first-time
+# registrations could both pass the zero-users check (TOCTOU). The yield
+# dependency holds the lock until the response completes, covering creation.
+# In-process only — multi-worker deployments retain a narrow race.
+_register_lock = asyncio.Lock()
+
+
+async def allow_registration():
+    """Gate registration to bootstrap-first-user only (issue #336).
+
+    Registration is permitted only while no *real* (login-capable) account
+    exists. The database always seeds a default admin (id=1) with a disabled
+    password placeholder; that account cannot log in and does not count.
+    Once the first real user registers, this raises 403.
+    """
+    async with _register_lock:
+        async_session_maker = get_async_session_maker()
+        async with async_session_maker() as session:
+            result = await session.execute(
+                select(func.count())
+                .select_from(User)
+                .where(User.hashed_password != _DISABLED_PASSWORD)
+            )
+            real_user_count = result.scalar_one()
+
+        if real_user_count > 0:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Registration is closed: an account already exists.",
+            )
+
+        # Hold the lock until the registration request finishes.
+        yield
+
+
+# Authentication routes (login, logout) - JWT endpoints at /auth/jwt/*
+router.include_router(
+    fastapi_users.get_auth_router(auth_backend),
+    prefix="/auth/jwt",
+    tags=["auth"],
+)
+
+# Registration route at /auth/register (bootstrap-first-user only)
+router.include_router(
+    fastapi_users.get_register_router(UserRead, UserCreate),
+    prefix="/auth",
+    tags=["auth"],
+    dependencies=[Depends(allow_registration)],
+)
+
+# User management routes (get me, update me) at /users/*
+router.include_router(
+    fastapi_users.get_users_router(UserRead, UserUpdate),
+    prefix="/users",
+    tags=["users"],
+)
+
+# Optional: Reset password, verify email
+# router.include_router(
+#     fastapi_users.get_reset_password_router(),
+#     prefix="/auth",
+#     tags=["auth"],
+# )
+# router.include_router(
+#     fastapi_users.get_verify_router(UserRead),
+#     prefix="/auth",
+#     tags=["auth"],
+# )
+
+# API key management routes at /api/auth/api-keys
+router.include_router(api_key_router)

codeframe/auth/schemas.py

@@ -0,0 +1,15 @@
+"""Pydantic schemas for user operations."""
+from typing import Optional
+from fastapi_users import schemas
+
+class UserRead(schemas.BaseUser[int]):
+    """Schema for reading user data."""
+    name: Optional[str] = None
+
+class UserCreate(schemas.BaseUserCreate):
+    """Schema for creating users."""
+    name: Optional[str] = None
+
+class UserUpdate(schemas.BaseUserUpdate):
+    """Schema for updating users."""
+    name: Optional[str] = None