beadhub 0.1.0__py3-none-any.whl

beadhub/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import version
+
+from .api import create_app
+from .cli import app
+from .db import DatabaseInfra
+
+__version__ = version("beadhub")
+__all__ = ["__version__", "create_app", "DatabaseInfra", "app", "main"]
+
+
+def main() -> None:
+    app()

beadhub/api.py

@@ -0,0 +1,260 @@
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+from aweb.routes.auth import router as aweb_auth_router
+from aweb.routes.chat import router as aweb_chat_router
+from aweb.routes.messages import router as aweb_messages_router
+from aweb.routes.projects import router as aweb_projects_router
+from aweb.routes.reservations import router as aweb_reservations_router
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.staticfiles import StaticFiles
+from redis.asyncio import Redis
+from redis.asyncio import from_url as async_redis_from_url
+
+from .config import get_settings
+from .db import DatabaseInfra
+from .db import db_infra as default_db_infra
+from .logging import configure_logging
+from .routes.agents import router as agents_router
+from .routes.bdh import router as bdh_router
+from .routes.beads import router as beads_router
+from .routes.claims import router as claims_router
+from .routes.escalations import router as escalations_router
+from .routes.init import router as init_router
+from .routes.mcp import router as mcp_router
+from .routes.policies import router as policies_router
+from .routes.status import router as status_router
+from .routes.subscriptions import router as subscriptions_router
+from .routes.workspaces import router as workspaces_router
+
+logger = logging.getLogger(__name__)
+
+
+def _make_standalone_lifespan():
+    """Create lifespan for standalone mode (creates own DB and Redis connections)."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        json_format = os.getenv("BEADHUB_LOG_JSON", "true").lower() == "true"
+        settings = get_settings()
+        configure_logging(log_level=settings.log_level, json_format=json_format)
+        logger.info("Starting BeadHub server (standalone mode)")
+
+        redis: Redis | None = None
+        redis_connected = False
+        db_initialized = False
+
+        try:
+            # Phase 1: Initialize all resources (don't set app.state yet)
+            redis = await async_redis_from_url(settings.redis_url, decode_responses=True)
+            await redis.ping()
+            redis_connected = True
+            logger.info("Connected to Redis")
+
+            await default_db_infra.initialize()
+            db_initialized = True
+            logger.info("Database initialized")
+
+            # Phase 2: Only assign to app.state after ALL initialization succeeds
+            app.state.redis = redis
+            app.state.db = default_db_infra
+
+        except Exception:
+            # Log which phase failed
+            if not redis_connected:
+                logger.exception("Failed to connect to Redis")
+            elif not db_initialized:
+                logger.exception("Failed to initialize database")
+
+            # Clean up any initialized resources on failure
+            if db_initialized:
+                await default_db_infra.close()
+            if redis is not None:
+                await redis.aclose()
+            raise
+
+        try:
+            yield
+        finally:
+            logger.info("Shutting down BeadHub server")
+            await redis.aclose()
+            await default_db_infra.close()
+
+    return lifespan
+
+
+def _make_library_lifespan(db_infra: DatabaseInfra, redis: Redis):
+    """Create lifespan for library mode (uses externally provided connections)."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        json_format = os.getenv("BEADHUB_LOG_JSON", "true").lower() == "true"
+        log_level = os.getenv("BEADHUB_LOG_LEVEL", "info")
+        configure_logging(log_level=log_level, json_format=json_format)
+        logger.info("Starting BeadHub server (library mode)")
+
+        # Use externally provided connections - no initialization needed
+        app.state.redis = redis
+        app.state.db = db_infra
+
+        try:
+            yield
+        finally:
+            # Don't close connections in library mode - caller manages them
+            logger.info("BeadHub server stopping (library mode)")
+
+    return lifespan
+
+
+def create_app(
+    *,
+    db_infra: Optional[DatabaseInfra] = None,
+    redis: Optional[Redis] = None,
+    serve_frontend: bool = True,
+    enable_bootstrap_routes: bool = True,
+) -> FastAPI:
+    """Create BeadHub FastAPI application.
+
+    Args:
+        db_infra: External DatabaseInfra instance (library mode).
+                  If None, creates own connections (standalone mode).
+        redis: External async Redis client (library mode).
+               If None, creates own connection (standalone mode).
+        serve_frontend: If True, serve the dashboard frontend from /frontend/dist.
+                        Set to False when embedding in another app that serves its own UI.
+        enable_bootstrap_routes: If True, expose bootstrap routes such as `/v1/init`.
+                                 Embedded/proxy deployments should set this to False.
+
+    Library mode requires both db_infra and redis to be provided.
+    Standalone mode requires neither (will create its own).
+
+    Examples:
+        Standalone mode (simple deployment)::
+
+            app = create_app()
+            # Run with: uvicorn beadhub.api:create_app --factory
+
+        Library mode (embedding in another FastAPI app)::
+
+            from beadhub.api import create_app
+            from beadhub.db import DatabaseInfra
+            from redis.asyncio import Redis
+
+            # Initialize shared infrastructure
+            db_infra = DatabaseInfra()
+            await db_infra.initialize()
+            redis = await Redis.from_url("redis://localhost:6379")
+
+            # Create BeadHub app with shared connections
+            beadhub_app = create_app(db_infra=db_infra, redis=redis)
+
+            # Mount under your main app
+            main_app.mount("/beadhub", beadhub_app)
+    """
+    # Validate mode consistency
+    if (db_infra is None) != (redis is None):
+        raise ValueError(
+            "Library mode requires both db_infra and redis, or neither for standalone mode"
+        )
+
+    library_mode = db_infra is not None
+
+    # Validate db_infra is initialized in library mode
+    if library_mode:
+        assert db_infra is not None  # Type narrowing for mypy
+        if not db_infra.is_initialized:
+            raise ValueError(
+                "db_infra must be initialized before passing to create_app() in library mode. "
+                "Call 'await db_infra.initialize()' before creating the app."
+            )
+        assert redis is not None  # Required when db_infra is provided
+        lifespan = _make_library_lifespan(db_infra, redis)
+    else:
+        lifespan = _make_standalone_lifespan()
+
+    app = FastAPI(title="BeadHub OSS Core", version="0.1.0", lifespan=lifespan)
+
+    @app.get("/health", tags=["internal"])
+    async def health(request: Request) -> dict:
+        checks = {}
+        healthy = True
+
+        # Check Redis
+        try:
+            redis: Redis = request.app.state.redis
+            await redis.ping()
+            checks["redis"] = "ok"
+        except Exception as e:
+            checks["redis"] = f"error: {e}"
+            healthy = False
+
+        # Check Database
+        try:
+            db_infra: DatabaseInfra = request.app.state.db
+            db = db_infra.get_manager("server")
+            await db.fetch_value("SELECT 1")
+            checks["database"] = "ok"
+        except Exception as e:
+            checks["database"] = f"error: {e}"
+            healthy = False
+
+        return {"status": "ok" if healthy else "unhealthy", "checks": checks}
+
+    # aweb protocol routes (BeadHub is an aweb server).
+    # Note: BeadHub overrides `/v1/init` with an extended init endpoint.
+    if enable_bootstrap_routes:
+        app.include_router(init_router)
+    app.include_router(aweb_auth_router)
+    app.include_router(aweb_chat_router)
+    app.include_router(aweb_messages_router)
+    app.include_router(aweb_projects_router)
+    app.include_router(aweb_reservations_router)
+
+    # beadhub endpoints.
+    app.include_router(bdh_router)
+    app.include_router(agents_router)
+    app.include_router(beads_router)
+    app.include_router(claims_router)
+    app.include_router(escalations_router)
+    app.include_router(policies_router)
+    app.include_router(status_router)
+    app.include_router(subscriptions_router)
+    app.include_router(workspaces_router)
+    app.include_router(mcp_router)
+
+    # Serve frontend dashboard if available and enabled
+    if serve_frontend:
+        # Look for frontend dist relative to this file's location
+        frontend_dist = Path(__file__).parent.parent.parent / "frontend" / "dist"
+        if frontend_dist.exists():
+            # Serve static assets
+            app.mount(
+                "/assets",
+                StaticFiles(directory=frontend_dist / "assets"),
+                name="assets",
+            )
+
+            # Serve index.html for all unmatched routes (SPA routing)
+            from fastapi.responses import FileResponse
+
+            @app.get("/{full_path:path}", include_in_schema=False)
+            async def serve_spa(full_path: str):
+                # API routes are handled by routers registered before this catch-all
+                # This only catches non-API paths for SPA routing
+                index_path = frontend_dist / "index.html"
+                if index_path.exists():
+                    return FileResponse(index_path)
+                raise HTTPException(status_code=404, detail="Frontend not found")
+
+            logger.info("Frontend dashboard enabled at /")
+        else:
+            logger.debug("Frontend not found at %s, skipping", frontend_dist)
+
+    return app
+
+
+# Module-level app for uvicorn: `uvicorn beadhub.api:app`
+app = create_app()

beadhub/auth.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any, Optional, Protocol
+
+from fastapi import HTTPException, Request
+
+from beadhub.aweb_introspection import get_identity_from_auth
+
+
+class DatabaseLike(Protocol):
+    def get_manager(self, name: str = "server") -> Any: ...
+
+
+def validate_workspace_id(workspace_id: str) -> str:
+    """Validate workspace_id is a valid UUID string and return normalized format."""
+    if workspace_id is None:
+        raise ValueError("workspace_id cannot be empty")
+    workspace_id = str(workspace_id).strip()
+    if not workspace_id:
+        raise ValueError("workspace_id cannot be empty")
+    try:
+        return str(uuid.UUID(workspace_id))
+    except ValueError:
+        raise ValueError("Invalid workspace_id format")
+
+
+async def get_workspace_project_id(
+    db: DatabaseLike,
+    workspace_id: str,
+) -> Optional[str]:
+    """Return project_id for workspace_id or None if not found."""
+    try:
+        ws_uuid = uuid.UUID(workspace_id)
+    except ValueError:
+        return None
+
+    server_db = db.get_manager("server")
+    row = await server_db.fetch_one(
+        """
+        SELECT project_id
+        FROM {{tables.workspaces}}
+        WHERE workspace_id = $1 AND deleted_at IS NULL
+        """,
+        ws_uuid,
+    )
+    if not row:
+        return None
+    return str(row["project_id"])
+
+
+async def verify_workspace_access(
+    request: Request,
+    workspace_id: str,
+    db: DatabaseLike,
+) -> str:
+    """Verify workspace_id belongs to the authenticated project, return project_id.
+
+    This enforces the invariant documented in `security-patterns.md`:
+    - project scope is derived from auth (API key or signed proxy context)
+    - workspace_id is validated and must belong to that project
+    - in direct Bearer mode, workspace-scoped operations MUST use the caller's identity
+    """
+    try:
+        workspace_id = validate_workspace_id(workspace_id)
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e))
+
+    identity = await get_identity_from_auth(request, db)
+    project_id = identity.project_id
+
+    server_db = db.get_manager("server")
+    row = await server_db.fetch_one(
+        """
+        SELECT project_id, deleted_at
+        FROM {{tables.workspaces}}
+        WHERE workspace_id = $1
+        """,
+        uuid.UUID(workspace_id),
+    )
+    if not row:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    if row.get("deleted_at") is not None:
+        raise HTTPException(status_code=410, detail="Workspace was deleted")
+
+    ws_project_id = str(row["project_id"])
+    if ws_project_id != project_id:
+        raise HTTPException(
+            status_code=403,
+            detail="Workspace not found or does not belong to your project",
+        )
+
+    # If auth provides an agent/actor identity, workspace-scoped operations must use it.
+    # This is enforced after existence checks so ghost workspaces still return 404/410.
+    if identity.agent_id is not None and identity.agent_id != workspace_id:
+        raise HTTPException(
+            status_code=403,
+            detail="workspace_id does not match API key identity",
+        )
+
+    return project_id

beadhub/aweb_context.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from aweb.auth import parse_bearer_token, verify_bearer_token_details
+from fastapi import HTTPException, Request
+
+
+@dataclass(frozen=True)
+class AwebIdentity:
+    project_id: str
+    project_slug: str
+    project_name: str
+    agent_id: str
+    alias: str
+    human_name: str
+
+
+async def resolve_aweb_identity(request: Request, db) -> AwebIdentity:
+    """Resolve the caller's aweb identity context.
+
+    BeadHub implements the aweb protocol and owns the aweb schema.
+    """
+    token = parse_bearer_token(request)
+    if token is None:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    details = await verify_bearer_token_details(db, token, manager_name="aweb")
+    project_id = (details.get("project_id") or "").strip()
+    agent_id = (details.get("agent_id") or "").strip()
+    if not project_id or not agent_id:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    aweb_db = db.get_manager("aweb")
+    agent = await aweb_db.fetch_one(
+        """
+        SELECT alias, human_name
+        FROM {{tables.agents}}
+        WHERE agent_id = $1 AND deleted_at IS NULL
+        """,
+        UUID(agent_id),
+    )
+    if not agent:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    project = await aweb_db.fetch_one(
+        """
+        SELECT slug, name
+        FROM {{tables.projects}}
+        WHERE project_id = $1 AND deleted_at IS NULL
+        """,
+        UUID(project_id),
+    )
+    if not project:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    return AwebIdentity(
+        project_id=project_id,
+        project_slug=project["slug"],
+        project_name=project.get("name") or "",
+        agent_id=agent_id,
+        alias=agent["alias"],
+        human_name=agent.get("human_name") or "",
+    )

beadhub/aweb_introspection.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from aweb.auth import DatabaseLike, parse_bearer_token, verify_bearer_token_details
+from fastapi import HTTPException, Request
+
+from .internal_auth import parse_internal_auth_context
+
+
+@dataclass(frozen=True)
+class AuthIdentity:
+    project_id: str
+    agent_id: str | None
+    api_key_id: str | None
+    user_id: str | None
+    auth_mode: str  # "proxy" or "bearer"
+
+
+async def get_identity_from_auth(request: Request, db: DatabaseLike) -> AuthIdentity:
+    """Resolve the authenticated identity context for BeadHub requests.
+
+    Priority order:
+    1) Trusted proxy/wrapper auth context (`X-BH-Auth` + `X-Project-ID`)
+    2) Local aweb Bearer API key (default; BeadHub implements the aweb protocol)
+    """
+    internal = parse_internal_auth_context(request)
+    if internal is not None:
+        principal_type = (internal.get("principal_type") or "").strip()
+        principal_id = (internal.get("principal_id") or "").strip() or None
+        actor_id = (internal.get("actor_id") or "").strip() or None
+        return AuthIdentity(
+            project_id=internal["project_id"],
+            agent_id=actor_id,
+            api_key_id=principal_id if principal_type == "k" else None,
+            user_id=principal_id if principal_type == "u" else None,
+            auth_mode="proxy",
+        )
+
+    token = parse_bearer_token(request)
+    if token is None:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    details = await verify_bearer_token_details(db, token, manager_name="aweb")
+    project_id = (details.get("project_id") or "").strip()
+    if not project_id:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    agent_id = (details.get("agent_id") or "").strip() or None
+    api_key_id = (details.get("api_key_id") or "").strip() or None
+    user_id = (details.get("user_id") or "").strip() or None
+    return AuthIdentity(
+        project_id=project_id,
+        agent_id=agent_id,
+        api_key_id=api_key_id,
+        user_id=user_id,
+        auth_mode="bearer",
+    )
+
+
+async def get_project_from_auth(request: Request, db: DatabaseLike) -> str:
+    """Resolve the authenticated project_id for BeadHub requests.
+
+    Priority order:
+    1) Trusted proxy/wrapper auth context (`X-BH-Auth` + `X-Project-ID`)
+    2) Local aweb auth (default; BeadHub implements the aweb protocol)
+    """
+    # 1) Proxy headers (signed internal context)
+    identity = await get_identity_from_auth(request, db)
+    return identity.project_id