octop 0.1.0.dev0__py3-none-any.whl

octop/__init__.py

@@ -0,0 +1,5 @@
+"""Octop — multi-user, multi-Agent self-hosted AI server."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

octop/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point: ``python -m octop`` → CLI."""
+
+from __future__ import annotations
+
+from octop.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

octop/api/__init__.py

@@ -0,0 +1 @@
+

octop/api/app.py

@@ -0,0 +1,204 @@
+"""FastAPI app factory."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, PlainTextResponse
+from scalar_fastapi import get_scalar_api_reference
+
+from octop.api.middleware.jwt_auth import install as install_jwt_auth
+from octop.api.middleware.setup_lockdown import install as install_setup_lockdown
+from octop.api.openapi_meta import API_DESCRIPTION, OPENAPI_TAGS, configure_openapi
+from octop.infra.errors import ErrorCode, OctopError
+from octop.infra.server import OctopServer
+from octop.infra.utils.locale import resolve_request_locale
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class _RouterMount:
+    router: Any
+    prefix: str
+    tags: Sequence[str]
+
+
+def _mount_routers(app: FastAPI, mounts: Sequence[_RouterMount]) -> None:
+    for spec in mounts:
+        app.include_router(spec.router, prefix=spec.prefix, tags=list(spec.tags))
+
+
+def _install_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(OctopError)
+    async def _octop(request: Request, exc: OctopError) -> JSONResponse:
+        locale = resolve_request_locale(request)
+        return JSONResponse(status_code=exc.status, content=exc.to_envelope(locale=locale))
+
+    @app.exception_handler(Exception)
+    async def _unhandled(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("unhandled exception in %s", request.url.path)
+        locale = resolve_request_locale(request)
+        err = OctopError.localized(ErrorCode.INTERNAL_ERROR, locale)
+        return JSONResponse(status_code=err.status, content=err.to_envelope())
+
+
+def build_app(server: OctopServer) -> FastAPI:
+    cfg = server.services.config if server.services else None
+    enable_dashboard = cfg.enable_dashboard if cfg else True
+    enable_api_docs = cfg.enable_api_docs if cfg else False
+
+    app = FastAPI(
+        title="Octop API",
+        version="0.1.0",
+        description=API_DESCRIPTION,
+        openapi_url="/api/openapi.json" if enable_api_docs else None,
+        openapi_tags=OPENAPI_TAGS,
+    )
+    configure_openapi(app)
+    app.state.octop_server = server
+    _install_exception_handlers(app)
+
+    if cfg and cfg.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    install_jwt_auth(app, server)
+    install_setup_lockdown(app, server)
+
+    from octop.infra.tls.challenge import challenge_store
+
+    @app.get("/.well-known/acme-challenge/{token}", include_in_schema=False)
+    async def acme_http01_challenge(token: str) -> PlainTextResponse:
+        body = challenge_store.get(token)
+        if body is None:
+            raise HTTPException(status_code=404, detail="challenge not found")
+        return PlainTextResponse(body)
+
+    from octop.api.routers import (
+        acp,
+        admin,
+        agent_files,
+        agents,
+        auth,
+        backup,
+        browser,
+        channels,
+        chat,
+        connectors,
+        cron,
+        envs,
+        experts,
+        health,
+        i18n,
+        internal_mcp,
+        mbti,
+        ollama_models,
+        plugins,
+        preferences,
+        providers,
+        setup,
+        skills,
+        slash,
+        terminal,
+        update,
+        usage,
+        users,
+        voice,
+        workspace,
+    )
+    from octop.api.routers.observability import router as observability_router
+    from octop.api.routers.providers import admin_router as admin_providers_router
+    from octop.api.routers.security import router as security_router
+    from octop.api.routers.storage_backends import admin_router as admin_storage_router
+    from octop.api.routers.storage_backends import user_router as storage_backends_user_router
+    from octop.api.routers.tls import router as tls_router
+    from octop.api.routers.voice import admin_router as admin_voice_router
+
+    _mount_routers(
+        app,
+        [
+            _RouterMount(setup.router, "/api", ["setup"]),
+            _RouterMount(auth.router, "/api/auth", ["auth"]),
+            _RouterMount(preferences.router, "/api", ["auth"]),
+            _RouterMount(i18n.router, "/api", ["i18n"]),
+            _RouterMount(health.router, "/api/health", ["health"]),
+            _RouterMount(users.router, "/api/users", ["users"]),
+            _RouterMount(agents.router, "/api/agents", ["agents"]),
+            _RouterMount(acp.router, "/api", ["agents"]),
+            _RouterMount(chat.router, "/api", ["chat"]),
+            _RouterMount(slash.router, "/api", ["slash"]),
+            _RouterMount(connectors.router, "/api", ["connectors"]),
+            _RouterMount(internal_mcp.router, "/api", ["internal-mcp"]),
+            _RouterMount(channels.router, "/api", ["channels"]),
+            _RouterMount(cron.router, "/api", ["cron"]),
+            _RouterMount(envs.router, "/api", ["envs"]),
+            _RouterMount(providers.router, "/api/providers", ["providers"]),
+            _RouterMount(voice.router, "/api/voice", ["voice"]),
+            _RouterMount(admin.router, "/api/admin", ["admin"]),
+            _RouterMount(backup.router, "/api/admin", ["admin"]),
+            _RouterMount(admin_providers_router, "/api/admin/providers", ["admin"]),
+            _RouterMount(admin_voice_router, "/api/admin/voice/providers", ["admin"]),
+            _RouterMount(observability_router, "/api/admin/observability", ["observability"]),
+            _RouterMount(tls_router, "/api/admin/tls", ["tls"]),
+            _RouterMount(security_router, "/api/admin/security", ["security"]),
+            _RouterMount(admin_storage_router, "/api/admin/storage-backends", ["admin"]),
+            _RouterMount(
+                storage_backends_user_router, "/api/storage-backends", ["storage-backends"]
+            ),
+            _RouterMount(mbti.router, "/api", ["mbti"]),
+            _RouterMount(experts.router, "/api", ["experts"]),
+            _RouterMount(workspace.router, "/api", ["workspace"]),
+            _RouterMount(agent_files.router, "/api", ["agent_files"]),
+            _RouterMount(usage.router, "/api", ["usage"]),
+            _RouterMount(usage.admin_router, "/api/admin", ["admin"]),
+            _RouterMount(skills.router, "/api", ["skills"]),
+            _RouterMount(terminal.router, "/api", ["terminal"]),
+            _RouterMount(update.router, "/api", ["update"]),
+            _RouterMount(browser.router, "/api", ["browser"]),
+            _RouterMount(ollama_models.router, "/api", ["ollama"]),
+            _RouterMount(plugins.router, "/api", ["plugins"]),
+        ],
+    )
+
+    if enable_api_docs:
+
+        @app.get("/api/docs", include_in_schema=False)
+        async def api_docs() -> HTMLResponse:
+            return get_scalar_api_reference(
+                openapi_url=app.openapi_url,
+                title="Octop API",
+            )
+
+    if enable_dashboard:
+        dashboard_dir = Path(__file__).parent.parent / "dashboard"
+        index_file = dashboard_dir / "index.html"
+        if index_file.exists():
+
+            @app.get("/{full_path:path}", include_in_schema=False)
+            async def spa_fallback(full_path: str) -> FileResponse:
+                if full_path.startswith(("api/", "ws/")):
+                    raise HTTPException(status_code=404, detail="Not Found")
+
+                if full_path:
+                    candidate = (dashboard_dir / full_path).resolve()
+                    try:
+                        candidate.relative_to(dashboard_dir.resolve())
+                    except ValueError:
+                        return FileResponse(index_file)
+                    if candidate.is_file():
+                        return FileResponse(candidate)
+                return FileResponse(index_file)
+
+    return app

octop/api/common/__init__.py

@@ -0,0 +1 @@
+"""Shared router helpers — agent access, workspace glue, request validation."""

octop/api/common/agent.py

@@ -0,0 +1,45 @@
+"""Shared agent ownership / existence checks for HTTP routers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from octop.infra.errors import ErrorCode, OctopError
+
+
+def assert_agent_owner(row: Any, user: Any) -> None:
+    """Raise if the user may not access this agent row (admin bypasses)."""
+    if user.is_admin:
+        return
+    if row.user_id is not None and row.user_id != user.id:
+        raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by user")
+
+
+def require_agent_row(
+    agent_id: str,
+    *,
+    user: Any,
+    as_user: int | None,
+    server: Any,
+) -> Any:
+    """Load an agent row after owner / shared-agent / admin ``as_user`` checks."""
+    assert server.app_runtime is not None
+    row = server.app_runtime.agent_registry.get_row(agent_id)
+    if row is None:
+        raise OctopError(ErrorCode.AGENT_NOT_FOUND, f"agent {agent_id!r} not found")
+    if as_user is not None and as_user != user.id:
+        if not user.is_admin:
+            raise OctopError(ErrorCode.FORBIDDEN, "as_user requires admin")
+        target = server.user_manager.get_by_id(as_user)
+        if target is None:
+            raise OctopError(ErrorCode.NOT_FOUND, f"user {as_user} not found")
+        if row.user_id is not None and row.user_id != as_user:
+            raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by as_user")
+    else:
+        assert_agent_owner(row, user)
+    return row
+
+
+def assert_agent_access(server: Any, agent_id: str, user: Any) -> None:
+    """Ensure agent exists and is accessible to the current user."""
+    require_agent_row(agent_id, user=user, as_user=None, server=server)

octop/api/common/validators.py

@@ -0,0 +1,49 @@
+"""Cross-router request validation helpers (no FastAPI route definitions)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from octop.infra.errors import ErrorCode, OctopError
+
+
+async def validate_chat_mcp_servers(
+    server: Any,
+    *,
+    user_id: int,
+    names: list[str] | None,
+) -> list[str] | None:
+    if not names:
+        return None
+    repo = server.services.repos.connector_repo
+    try:
+        return list(repo.validate_mcp_servers_for_user(user_id, names))
+    except ValueError as exc:
+        raise OctopError(ErrorCode.CONNECTOR_NOT_BOUND, str(exc)) from exc
+
+
+async def validate_chat_skills(
+    server: Any,
+    *,
+    agent_id: str,
+    user: Any,
+    names: list[str] | None,
+) -> list[str] | None:
+    """Validate per-turn skill filter for chat.
+
+    ``None`` leaves the full skill set; ``[]`` disables all skills.
+    """
+    if names is None:
+        return None
+    assert server.app_runtime is not None
+    allowed: set[str] = set()
+    for summary in await server.app_runtime.agent_registry.list_skill_summaries(agent_id):
+        if summary.get("enabled"):
+            allowed.add(str(summary["name"]))
+    bad = [n for n in names if n not in allowed]
+    if bad:
+        raise OctopError(
+            ErrorCode.NOT_FOUND,
+            f"skill(s) not found or disabled: {', '.join(bad)}",
+        )
+    return list(names)

octop/api/common/workspace.py

@@ -0,0 +1,57 @@
+"""Shared workspace backend helpers (not route handlers)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from octop.api.common.agent import require_agent_row
+
+# deepagents.backends.utils.EMPTY_CONTENT_WARNING — shown to LLM tools, not humans.
+_DEEPAGENTS_EMPTY_WARNING = "System reminder: File exists but has empty contents"
+
+
+def coerce_read_content(content: Any) -> str:
+    """Normalize backend read payloads for the dashboard file viewer."""
+    if content is None:
+        return ""
+    if isinstance(content, list):
+        content = "\n".join(str(line) for line in content)
+    text = str(content)
+    if text == _DEEPAGENTS_EMPTY_WARNING:
+        return ""
+    return text
+
+
+async def resolve_agent_backend(
+    agent_id: str,
+    *,
+    user: Any,
+    as_user: int | None,
+    server: Any,
+) -> Any:
+    """Get the harness workspace backend for file operations."""
+    require_agent_row(agent_id, user=user, as_user=as_user, server=server)
+    assert server.app_runtime is not None
+    return await server.app_runtime.agent_registry.resolve_harness_backend(agent_id)
+
+
+def file_info_to_dict(info: Any) -> dict[str, Any]:
+    """Coerce a ``FileInfo`` TypedDict into a JSON-friendly dict."""
+    if isinstance(info, dict):
+        path = info.get("path")
+        is_dir = info.get("is_dir")
+        size = info.get("size")
+        modified_at = info.get("modified_at")
+    else:
+        path = getattr(info, "path", None)
+        is_dir = getattr(info, "is_dir", None)
+        size = getattr(info, "size", None)
+        modified_at = getattr(info, "modified_at", None)
+    out: dict[str, Any] = {"path": path}
+    if is_dir is not None:
+        out["is_dir"] = bool(is_dir)
+    if size is not None:
+        out["size"] = int(size)
+    if modified_at is not None:
+        out["modified_at"] = modified_at
+    return out

octop/api/deps.py

@@ -0,0 +1,144 @@
+"""FastAPI Depends, JWT helpers, and auth routing."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, cast
+
+import jwt
+from fastapi import Depends, Header, Query, Request
+
+from octop.infra.errors import ErrorCode, OctopError
+
+if TYPE_CHECKING:
+    from octop.infra.server import OctopServer
+    from octop.infra.users.identity import User
+
+
+class InvalidToken(Exception): ...
+
+
+class TokenExpired(InvalidToken): ...
+
+
+def sign_token(
+    secret: bytes,
+    *,
+    sub: int,
+    uname: str,
+    role: str,
+    ttl_seconds: int = 86400,
+) -> str:
+    now = int(time.time())
+    payload = {
+        "sub": str(sub),
+        "uname": uname,
+        "role": role,
+        "iat": now,
+        "exp": now + ttl_seconds,
+    }
+    return jwt.encode(payload, secret, algorithm="HS256")
+
+
+def decode_token(secret: bytes, token: str) -> dict[str, Any]:
+    try:
+        payload = jwt.decode(token, secret, algorithms=["HS256"])
+        if "sub" in payload:
+            payload["sub"] = int(payload["sub"])
+        return payload
+    except jwt.ExpiredSignatureError as exc:
+        raise TokenExpired() from exc
+    except jwt.InvalidTokenError as exc:
+        raise InvalidToken(str(exc)) from exc
+
+
+# Paths that bypass JWT middleware (setup wizard, health, login).
+_JWT_EXEMPT_PREFIXES = (
+    "/api/setup/",
+    "/api/health/",
+    "/api/i18n/",
+    "/api/connectors/oauth/callback",
+    "/api/internal/mcp/",
+)
+_JWT_EXEMPT_EXACT = (
+    "/api/health",
+    "/api/auth/login",
+    "/api/docs",
+    "/api/openapi.json",
+)
+
+
+def is_jwt_exempt_path(path: str) -> bool:
+    return path in _JWT_EXEMPT_EXACT or any(path.startswith(p) for p in _JWT_EXEMPT_PREFIXES)
+
+
+def get_server(request: Request) -> OctopServer:
+    server: OctopServer = request.app.state.octop_server
+    if server.services is None or server.app_runtime is None:
+        raise OctopError(ErrorCode.INTERNAL_ERROR, "server not started")
+    return server
+
+
+def extract_raw_token(
+    *,
+    authorization: str | None = None,
+    access_token: str | None = None,
+) -> str | None:
+    if authorization and authorization.lower().startswith("bearer "):
+        return authorization[7:].strip()
+    if access_token:
+        return access_token
+    return None
+
+
+def _decode(server: OctopServer, token: str) -> dict[str, Any]:
+    assert server.services is not None
+    secret = server.services.secret_repo.get("jwt")
+    if secret is None:
+        raise OctopError(ErrorCode.INTERNAL_ERROR, "jwt secret missing")
+    try:
+        return decode_token(secret, token)
+    except TokenExpired as exc:
+        raise OctopError(ErrorCode.TOKEN_EXPIRED, "token expired") from exc
+    except InvalidToken as exc:
+        raise OctopError(ErrorCode.AUTH_FAILED, "invalid token") from exc
+
+
+def resolve_user_from_token(server: OctopServer, token: str) -> User:
+    payload = _decode(server, token)
+    assert server.user_manager is not None
+    user = server.user_manager.get_by_id(int(payload["sub"]))
+    if user is None:
+        raise OctopError(ErrorCode.USER_DISABLED, "user not active")
+    return user
+
+
+def authenticate_request(request: Request, server: OctopServer) -> User:
+    raw = extract_raw_token(
+        authorization=request.headers.get("authorization"),
+        access_token=request.query_params.get("access_token"),
+    )
+    if not raw:
+        raise OctopError(ErrorCode.AUTH_FAILED, "missing credentials")
+    return resolve_user_from_token(server, raw)
+
+
+async def current_user(
+    request: Request,
+    server: OctopServer = Depends(get_server),
+    authorization: str | None = Header(None),
+    access_token: str | None = Query(None),
+) -> User:
+    cached = getattr(request.state, "octop_user", None)
+    if cached is not None:
+        return cast("User", cached)
+    raw = extract_raw_token(authorization=authorization, access_token=access_token)
+    if not raw:
+        raise OctopError(ErrorCode.AUTH_FAILED, "missing credentials")
+    return resolve_user_from_token(server, raw)
+
+
+async def current_admin(user: User = Depends(current_user)) -> User:
+    if not user.is_admin:
+        raise OctopError(ErrorCode.FORBIDDEN, "admin required")
+    return user

octop/api/middleware/__init__.py

@@ -0,0 +1 @@
+"""ASGI middlewares for octop."""

octop/api/middleware/jwt_auth.py

@@ -0,0 +1,40 @@
+"""Require JWT for all /api/* routes except an explicit allowlist.
+
+Validated users are cached on ``request.state.octop_user`` so route-level
+``Depends(current_user)`` can reuse the result without re-decoding.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from octop.api.deps import authenticate_request, is_jwt_exempt_path
+from octop.infra.errors import OctopError
+
+_INSTALL_ATTR = "_octop_jwt_auth_installed"
+
+
+def install(app: Any, server: Any) -> None:
+    if getattr(app, _INSTALL_ATTR, False):
+        return
+    setattr(app, _INSTALL_ATTR, True)
+
+    @app.middleware("http")  # type: ignore[untyped-decorator]
+    async def _jwt_auth(
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Any]],
+    ) -> Any:
+        path = request.url.path
+        if not path.startswith("/api/") or is_jwt_exempt_path(path):
+            return await call_next(request)
+
+        try:
+            request.state.octop_user = authenticate_request(request, server)
+        except OctopError as exc:
+            return JSONResponse(status_code=exc.status, content=exc.to_envelope())
+
+        return await call_next(request)

octop/api/middleware/setup_lockdown.py

@@ -0,0 +1,41 @@
+"""Lock down all non-/setup endpoints while no users exist.
+
+Returns ``503 {"setup_required": true}`` so the SPA can hard-redirect
+to ``/setup``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+_OPEN_PREFIXES = (
+    "/api/setup/",
+    "/api/health/",
+)
+
+
+def install(app: Any, server: Any) -> None:
+    @app.middleware("http")
+    async def _lockdown(
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Any]],
+    ) -> Any:
+        path = request.url.path
+        if not path.startswith("/api/"):
+            return await call_next(request)
+        cfg = server.services.config if server.services else None
+        open_exact = ["/api/health"]
+        if cfg and cfg.enable_api_docs:
+            open_exact.extend(("/api/docs", "/api/openapi.json"))
+        if path in open_exact or any(path.startswith(p) for p in _OPEN_PREFIXES):
+            return await call_next(request)
+        if server.user_manager is None or server.user_manager.count() == 0:
+            return JSONResponse(
+                status_code=503,
+                content={"setup_required": True},
+            )
+        return await call_next(request)