deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/outputs.py

@@ -0,0 +1,97 @@
+"""Request-scoped delivery of generated output artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import FileResponse
+
+from deeptutor.api.routers.auth import require_auth
+from deeptutor.multi_user.context import get_current_user_or_none
+from deeptutor.multi_user.partner_access import visible_partners
+from deeptutor.multi_user.paths import get_current_path_service, get_path_service_for_scope
+from deeptutor.services.auth import TokenPayload
+from deeptutor.services.path_service import PathService
+
+router = APIRouter()
+
+# Video lessons are pages of model-written script. Served under this CSP they
+# run in an opaque origin even when opened directly, never with the API's
+# cookies or same-origin access.
+_SANDBOXED_PAGE_CSP = "sandbox allow-scripts allow-popups"
+
+
+def _request_path_service() -> PathService:
+    """Resolve the workspace installed by ``require_auth`` without fallback.
+
+    The general-purpose ``get_path_service()`` retains a compatibility fallback
+    to the local admin workspace for non-request callers.  A download endpoint
+    must fail closed instead: otherwise an authentication/context regression
+    could expose an administrator artifact to an ordinary request.
+    """
+    user = get_current_user_or_none()
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Output not found")
+    return get_current_path_service()
+
+
+def _resolve_output(path_service: PathService, relative_path: str) -> Path:
+    output_path = path_service.resolve_public_output_path(relative_path)
+    if output_path is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Output not found")
+    return output_path
+
+
+def _resolve_partner_output(relative_path: str) -> Path | None:
+    """Resolve *relative_path* against partner scopes the caller may use.
+
+    Partner web chats run inside a synthetic workspace under
+    ``data/partners/<id>/workspace``, so generated files are not beneath the
+    human caller's own ``data/users/<uid>`` tree. The public artifact URL shape
+    is still ``/files/outputs/<relative path>``, which means the download surface
+    has to search the caller's visible partner workspaces when their own
+    workspace misses (#1012).
+
+    The first-party chat flow already scopes the request to one conversation, so
+    the same relative path colliding across multiple partners is vanishingly
+    unlikely. Fail closed anyway: only a unique partner match is served.
+    """
+    from deeptutor.modules.catalog import module_enabled
+    from deeptutor.services.workspace.context import current_workspace_id
+
+    if current_workspace_id() or not module_enabled("partners"):
+        return None
+    from deeptutor.services.partners.scope import partner_scope
+
+    matches: list[Path] = []
+    for partner in visible_partners():
+        partner_id = str(partner.get("partner_id") or "").strip()
+        if not partner_id:
+            continue
+        candidate = get_path_service_for_scope(
+            partner_scope(partner_id)
+        ).resolve_public_output_path(relative_path)
+        if candidate is not None:
+            matches.append(candidate)
+            if len(matches) > 1:
+                return None
+    return matches[0] if matches else None
+
+
+@router.get("/{output_path:path}", operation_id="read_output_get")
+@router.head("/{output_path:path}", operation_id="read_output_head")
+async def read_output(
+    output_path: str,
+    _auth: TokenPayload | None = Depends(require_auth),
+) -> FileResponse:
+    """Serve one allowlisted artifact from the authenticated user's reach."""
+    try:
+        path = _resolve_output(_request_path_service(), output_path)
+    except HTTPException:
+        path = _resolve_partner_output(output_path)
+        if path is None:
+            raise
+    if path.suffix.lower() == ".html" and "video_lesson" in path.parts:
+        return FileResponse(path, headers={"Content-Security-Policy": _SANDBOXED_PAGE_CSP})
+    return FileResponse(path)

deeptutor/api/routers/personas.py

@@ -0,0 +1,154 @@
+"""
+Personas API Router
+===================
+
+CRUD endpoints for user-authored PERSONA.md files stored under
+``data/user/workspace/personas/<name>/PERSONA.md``.
+
+Personas are behaviour/voice presets, not capability skills: admin-authored
+personas are visible to every user as read-only deployment presets (no grant
+mechanism — a persona carries no privileged workflow, only style guidance).
+Users create and manage their own personas in their own workspace; a user
+persona shadows an admin persona of the same name.
+
+Mounted at ``/api/personas``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from deeptutor.multi_user.paths import get_admin_path_service
+from deeptutor.services.i18n import t
+from deeptutor.services.persona import (
+    InvalidPersonaNameError,
+    PersonaExistsError,
+    PersonaNotFoundError,
+    PersonaService,
+    get_persona_service,
+)
+
+router = APIRouter()
+
+
+class CreatePersonaRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=64)
+    description: str = ""
+    content: str = ""
+
+
+class UpdatePersonaRequest(BaseModel):
+    description: str | None = None
+    content: str | None = None
+    rename_to: str | None = None
+
+
+def _admin_persona_service() -> PersonaService:
+    return PersonaService(root=get_admin_path_service().get_workspace_dir() / "personas")
+
+
+def _persona_presets(service: PersonaService) -> PersonaService | None:
+    """The read-only deployment presets, unless ``service`` already holds them.
+
+    ``None`` means the caller is reading the very directory the presets live in
+    — the admin on their account-level workspace — where merging would only
+    duplicate every row. Deciding that on ``user.is_admin`` instead took "the
+    caller is an admin" to mean "the caller is reading the preset directory",
+    which stopped being true once each workspace got its own personas
+    directory: inside an explicit workspace an admin saw nothing but Default
+    while a non-admin on the same workspace saw every preset (#1534).
+    """
+    presets = _admin_persona_service()
+    if presets.root.resolve() == service.root.resolve():
+        return None
+    return presets
+
+
+@router.get("/personas")
+async def list_personas() -> dict[str, list[dict[str, object]]]:
+    service = get_persona_service()
+    own = [info.to_dict() for info in service.list_personas()]
+    presets = _persona_presets(service)
+    if presets is None:
+        return {"personas": own}
+    own_names = {item["name"] for item in own}
+    merged = list(own)
+    for preset in presets.list_personas():
+        if preset.name in own_names:
+            continue
+        entry = preset.to_dict()
+        entry.update({"source": "admin", "read_only": True})
+        merged.append(entry)
+    return {"personas": merged}
+
+
+@router.get("/personas/{name}")
+async def get_persona(name: str) -> dict[str, object]:
+    service = get_persona_service()
+    try:
+        return service.get_detail(name).to_dict()
+    except PersonaNotFoundError:
+        pass
+    except InvalidPersonaNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    presets = _persona_presets(service)
+    if presets is not None:
+        try:
+            detail = presets.get_detail(name).to_dict()
+            detail.update({"source": "admin", "read_only": True})
+            return detail
+        except (PersonaNotFoundError, InvalidPersonaNameError):
+            pass
+    raise HTTPException(status_code=404, detail=t("api.persona_not_found", name=name))
+
+
+@router.post("/personas")
+async def create_persona(payload: CreatePersonaRequest) -> dict[str, object]:
+    service = get_persona_service()
+    try:
+        info = service.create(
+            name=payload.name,
+            description=payload.description,
+            content=payload.content,
+        )
+        return info.to_dict()
+    except PersonaExistsError:
+        raise HTTPException(
+            status_code=409,
+            detail=t("api.persona_already_exists", name=payload.name),
+        )
+    except InvalidPersonaNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.put("/personas/{name}")
+async def update_persona(name: str, payload: UpdatePersonaRequest) -> dict[str, object]:
+    service = get_persona_service()
+    try:
+        info = service.update(
+            name,
+            description=payload.description,
+            content=payload.content,
+            rename_to=payload.rename_to,
+        )
+        return info.to_dict()
+    except PersonaNotFoundError:
+        raise HTTPException(status_code=404, detail=t("api.persona_not_found", name=name))
+    except PersonaExistsError as exc:
+        raise HTTPException(status_code=409, detail=str(exc))
+    except InvalidPersonaNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.delete("/personas/{name}")
+async def delete_persona(name: str) -> dict[str, str]:
+    service = get_persona_service()
+    try:
+        service.delete(name)
+        return {"status": "deleted", "name": name}
+    except PersonaNotFoundError:
+        raise HTTPException(status_code=404, detail=t("api.persona_not_found", name=name))
+    except InvalidPersonaNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

deeptutor/api/routers/plugins.py

@@ -0,0 +1,416 @@
+"""Authenticated introspection and managed plugin HTTP route dispatch."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, Response
+from pydantic import BaseModel, Field
+
+from deeptutor.api.routers.auth import AUTH_COOKIE_NAME, require_admin, require_auth
+from deeptutor.plugins.catalog import load_catalog
+from deeptutor.plugins.distribution import CatalogInstallManager, PluginDistributionError
+from deeptutor.plugins.frontend import (
+    FrontendPageError,
+    load_frontend_page_manifest,
+    resolve_frontend_page_asset,
+)
+from deeptutor.plugins.lifecycle import PluginLifecycleError, PluginLifecycleManager
+from deeptutor.plugins.manifest import PluginExtension
+from deeptutor.plugins.registry import (
+    PluginInstallation,
+    PluginRecord,
+    PluginRegistry,
+    PluginStateError,
+)
+from deeptutor.plugins.runtime import (
+    PluginHttpResponse,
+    PluginRuntimeError,
+    PluginWorkerHttpRoute,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+_registry_factory = PluginRegistry
+_MAX_JSON_BODY_BYTES = 1024 * 1024
+_FRONTEND_CSP = (
+    "default-src 'none'; "
+    "script-src 'self'; "
+    "style-src 'self' 'unsafe-inline'; "
+    "img-src 'self' data: blob:; "
+    "font-src 'self' data:; "
+    "media-src 'self' data: blob:; "
+    "connect-src 'none'; frame-src 'none'; object-src 'none'; "
+    "base-uri 'none'; form-action 'none'; frame-ancestors 'self'; "
+    "sandbox allow-scripts"
+)
+
+
+async def _require_authenticated(request: Request):
+    return await require_auth(
+        authorization=request.headers.get("Authorization"),
+        dt_token=request.cookies.get(AUTH_COOKIE_NAME),
+        request=request,
+    )
+
+
+async def _require_admin(request: Request):
+    return await require_admin(
+        payload=await _require_authenticated(request),
+    )
+
+
+def _managed_records(registry: PluginRegistry) -> list[PluginRecord]:
+    return [
+        record
+        for record in registry.list_plugins(include_catalog=False)
+        if record.status == "enabled"
+        and record.distribution == "managed"
+        and record.manifest is not None
+        and record.installation is not None
+    ]
+
+
+def _extensions_payload(records: list[PluginRecord]) -> list[dict[str, Any]]:
+    result: list[dict[str, Any]] = []
+    for record in records:
+        if record.manifest is None:
+            continue
+        extensions: list[dict[str, Any]] = []
+        for extension in record.manifest.extensions:
+            payload = extension.to_dict()
+            if extension.type == "frontend_page" and extension.manifest:
+                payload["entry_url"] = f"/api/plugins/{record.id}/pages/{extension.id}/"
+            extensions.append(payload)
+        result.append(
+            {
+                "id": record.id,
+                "name": record.name,
+                "version": record.version,
+                "extensions": extensions,
+            }
+        )
+    return result
+
+
+def _find_route(
+    *,
+    plugin_id: str,
+    plugin_path: str,
+) -> tuple[PluginRecord, PluginExtension, PluginInstallation] | None:
+    normalized_path = _normalize_plugin_path(plugin_path)
+    if normalized_path is None:
+        return None
+    for record in _managed_records(_registry_factory()):
+        if record.id != plugin_id or record.manifest is None or record.installation is None:
+            continue
+        for extension in record.manifest.extensions:
+            if extension.type == "http_route" and extension.path == normalized_path:
+                return record, extension, record.installation
+    return None
+
+
+def _find_frontend_page(
+    *,
+    plugin_id: str,
+    extension_id: str,
+) -> tuple[PluginRecord, PluginExtension, PluginInstallation, Path] | None:
+    for record in _managed_records(_registry_factory()):
+        if record.id != plugin_id or record.manifest is None or record.installation is None:
+            continue
+        if record.installation.package_path is None:
+            continue
+        for extension in record.manifest.extensions:
+            if extension.type == "frontend_page" and extension.id == extension_id:
+                return record, extension, record.installation, record.installation.package_path
+    return None
+
+
+def _normalize_plugin_path(value: str) -> str | None:
+    if not value or "\x00" in value or "%" in value or "\\" in value:
+        return None
+    return "/" + value.strip("/")
+
+
+async def _authenticate_plugin_route(request: Request) -> None:
+    payload = await _require_authenticated(request)
+    matched = _find_route(
+        plugin_id=request.path_params["plugin_id"],
+        plugin_path=request.path_params["plugin_path"],
+    )
+    if matched is None:
+        return
+    request.state.plugin_route = matched
+    policy = matched[1].auth
+    if policy == "admin":
+        await require_admin(payload=payload)
+
+
+async def _authenticate_plugin_page(request: Request) -> None:
+    payload = await _require_authenticated(request)
+    matched = _find_frontend_page(
+        plugin_id=request.path_params["plugin_id"],
+        extension_id=request.path_params["extension_id"],
+    )
+    if matched is None:
+        return
+    request.state.plugin_page = matched
+    policy = matched[1].auth
+    if policy == "admin":
+        await require_admin(payload=payload)
+
+
+@router.get("/extensions", dependencies=[Depends(_require_authenticated)])
+def list_extensions() -> dict[str, Any]:
+    return {"plugins": _extensions_payload(_managed_records(_registry_factory()))}
+
+
+@router.get(
+    "/{plugin_id}/pages/{extension_id}",
+    dependencies=[Depends(_authenticate_plugin_page)],
+)
+def redirect_plugin_frontend_page(request: Request) -> RedirectResponse:
+    matched = getattr(request.state, "plugin_page", None)
+    if matched is None:
+        raise HTTPException(status_code=404, detail="Plugin page not found")
+    return RedirectResponse(url=f"{request.url.path}/", status_code=307)
+
+
+@router.get(
+    "/{plugin_id}/pages/{extension_id}/",
+    dependencies=[Depends(_authenticate_plugin_page)],
+)
+def get_plugin_frontend_page(request: Request) -> FileResponse:
+    matched = getattr(request.state, "plugin_page", None)
+    if matched is None:
+        raise HTTPException(status_code=404, detail="Plugin page not found")
+    _, extension, _, package_path = matched
+    if not extension.manifest:
+        raise HTTPException(status_code=404, detail="Plugin page not found")
+    try:
+        page = load_frontend_page_manifest(package_path / extension.manifest)
+        path = resolve_frontend_page_asset(page, package_path, page.entry)
+    except FrontendPageError as exc:
+        logger.warning(
+            "Managed frontend page %s/%s failed validation",
+            matched[0].id,
+            extension.id,
+            exc_info=exc,
+        )
+        raise HTTPException(status_code=404, detail="Plugin page not found") from exc
+    return _frontend_file_response(path)
+
+
+@router.get(
+    "/{plugin_id}/pages/{extension_id}/assets/{asset_path:path}",
+    dependencies=[Depends(_authenticate_plugin_page)],
+)
+def get_plugin_frontend_asset(request: Request) -> FileResponse:
+    matched = getattr(request.state, "plugin_page", None)
+    if matched is None:
+        raise HTTPException(status_code=404, detail="Plugin page not found")
+    _, extension, _, package_path = matched
+    if not extension.manifest:
+        raise HTTPException(status_code=404, detail="Plugin page not found")
+    requested = request.path_params["asset_path"]
+    try:
+        page = load_frontend_page_manifest(package_path / extension.manifest)
+        path = resolve_frontend_page_asset(page, package_path, requested)
+    except FrontendPageError as exc:
+        logger.warning(
+            "Managed frontend asset %s/%s failed validation",
+            matched[0].id,
+            extension.id,
+            exc_info=exc,
+        )
+        raise HTTPException(status_code=404, detail="Plugin page not found") from exc
+    return _frontend_file_response(path, asset=True)
+
+
+async def dispatch_plugin_route(request: Request) -> Response:
+    matched = getattr(request.state, "plugin_route", None)
+    if matched is None:
+        raise HTTPException(status_code=404, detail="Plugin route not found")
+    record, extension, installation = matched
+    if request.method not in extension.methods:
+        raise HTTPException(
+            status_code=405,
+            detail="Method not allowed",
+            headers={"Allow": ", ".join(extension.methods)},
+        )
+
+    chunks = []
+    size = 0
+    async for chunk in request.stream():
+        size += len(chunk)
+        if size > _MAX_JSON_BODY_BYTES:
+            raise HTTPException(status_code=413, detail="Plugin request body is too large")
+        chunks.append(chunk)
+    raw_body = b"".join(chunks)
+    body = None
+    if raw_body:
+        try:
+            body = json.loads(raw_body)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail="Request body must be JSON") from exc
+
+    query: dict[str, tuple[str, ...]] = {
+        name: tuple(request.query_params.getlist(name)) for name in request.query_params.keys()
+    }
+    worker = PluginWorkerHttpRoute(
+        manifest=record.manifest,
+        installation=installation,
+        extension_id=extension.id,
+        registry=_registry_factory(),
+    )
+    try:
+        result = await asyncio.to_thread(
+            worker.handle,
+            method=request.method,
+            path=extension.path,
+            query=query,
+            body=body,
+        )
+    except PluginRuntimeError as exc:
+        logger.warning(
+            "Managed HTTP route %s/%s failed its worker contract",
+            record.id,
+            extension.id,
+            exc_info=exc,
+        )
+        raise HTTPException(status_code=500, detail="Plugin route failed") from exc
+    return _http_response(result)
+
+
+class ApprovalRequest(BaseModel):
+    snapshot_digest: str = Field(pattern="^[0-9a-f]{64}$")
+
+
+class InstallRequest(BaseModel):
+    version: str = Field(default="latest", max_length=64)
+    allow_deprecated: bool = False
+
+
+@router.get("/catalog", dependencies=[Depends(_require_authenticated)])
+def plugin_catalog():
+    return {"entries": [entry.to_dict() for entry in load_catalog()]}
+
+
+@router.get("/state", dependencies=[Depends(_require_authenticated)])
+def plugin_state():
+    return {"plugins": [record.to_dict() for record in _registry_factory().list_plugins()]}
+
+
+@router.get("/{plugin_id}/info", dependencies=[Depends(_require_authenticated)])
+def plugin_info(plugin_id: str):
+    record = _registry_factory().get_plugin(plugin_id)
+    if record is None:
+        raise HTTPException(404, "Plugin not found")
+    return record.to_dict()
+
+
+@router.post("/{plugin_id}/approve", dependencies=[Depends(_require_admin)])
+def approve_plugin(plugin_id: str, payload: ApprovalRequest):
+    try:
+        return (
+            _registry_factory()
+            .approve(plugin_id, expected_digest=payload.snapshot_digest)
+            .to_dict()
+        )
+    except PluginStateError as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@router.post("/{plugin_id}/enable", dependencies=[Depends(_require_admin)])
+def enable_plugin(plugin_id: str):
+    try:
+        return _registry_factory().set_enabled(plugin_id, True).to_dict()
+    except PluginStateError as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@router.post("/{plugin_id}/disable", dependencies=[Depends(_require_admin)])
+def disable_plugin(plugin_id: str):
+    try:
+        return _registry_factory().set_enabled(plugin_id, False).to_dict()
+    except PluginStateError as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@router.post("/{plugin_id}/install", dependencies=[Depends(_require_admin)])
+def install_plugin(plugin_id: str, payload: InstallRequest):
+    try:
+        result = CatalogInstallManager(
+            lifecycle_factory=lambda: PluginLifecycleManager(registry=_registry_factory())
+        ).install(plugin_id, version=payload.version, allow_deprecated=payload.allow_deprecated)
+        return {
+            "id": result.lifecycle.plugin_id,
+            "version": result.lifecycle.version,
+            "action": result.lifecycle.action,
+            "approval_required": True,
+        }
+    except (PluginStateError, PluginLifecycleError, PluginDistributionError) as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@router.post("/{plugin_id}/rollback", dependencies=[Depends(_require_admin)])
+def rollback_plugin(plugin_id: str):
+    try:
+        result = PluginLifecycleManager(registry=_registry_factory()).rollback(plugin_id)
+        return {"id": result.plugin_id, "version": result.version, "approval_required": True}
+    except (PluginStateError, PluginLifecycleError) as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@router.delete("/{plugin_id}/installation", dependencies=[Depends(_require_admin)])
+def uninstall_plugin(plugin_id: str):
+    try:
+        result = PluginLifecycleManager(registry=_registry_factory()).uninstall(plugin_id)
+        return {"id": result.plugin_id, "action": result.action}
+    except (PluginStateError, PluginLifecycleError) as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+for _method in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+    router.add_api_route(
+        "/{plugin_id}/{plugin_path:path}",
+        dispatch_plugin_route,
+        methods=[_method],
+        operation_id=f"dispatch_plugin_route_{_method.lower()}",
+        dependencies=[Depends(_authenticate_plugin_route)],
+    )
+
+
+def _http_response(result: PluginHttpResponse) -> Response:
+    if result.status == 204:
+        return Response(status_code=204, headers=dict(result.headers or {}))
+    return JSONResponse(
+        status_code=result.status,
+        content=result.body,
+        headers=dict(result.headers or {}),
+    )
+
+
+def _frontend_file_response(path: Path, *, asset: bool = False) -> FileResponse:
+    media_type = "text/html; charset=utf-8" if path.suffix.lower() == ".html" else None
+    return FileResponse(
+        path,
+        media_type=media_type,
+        headers={
+            "Cache-Control": "no-store",
+            "Vary": "Authorization, Cookie",
+            "Content-Security-Policy": _FRONTEND_CSP,
+            "Cross-Origin-Resource-Policy": "cross-origin" if asset else "same-origin",
+            "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+            "Referrer-Policy": "no-referrer",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+__all__ = ["router"]