Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

20.5 KB
Raw Blame
"""HTTP and introspection contracts for managed plugin extensions."""

from __future__ import annotations

import base64
import hashlib
from html.parser import HTMLParser
import json
from pathlib import Path
import sys
from typing import Any
from urllib.parse import urljoin
import zipfile

import pytest

try:
    from fastapi import FastAPI, HTTPException, Request
    from fastapi.testclient import TestClient
except Exception:  # pragma: no cover
    FastAPI = None
    TestClient = None

from deeptutor.plugins.lifecycle import PluginLifecycleManager
from deeptutor.plugins.manifest import parse_manifest
from deeptutor.plugins.registry import PluginInstallation, PluginRegistry
from deeptutor.plugins.runtime import PluginHttpResponse

pytestmark = pytest.mark.skipif(
    FastAPI is None or TestClient is None, reason="fastapi not installed"
)


def _raw_manifest() -> dict[str, Any]:
    return {
        "schema_version": "deeptutor.plugin/v1",
        "id": "org.deeptutor.learning_echo",
        "name": "Learning Echo Example",
        "version": "1.0.0",
        "description_i18n": {"en": "Example"},
        "author": "DeepTutor",
        "license": "Apache-2.0",
        "homepage": "https://example.com",
        "source_url": "https://example.com/source",
        "compatibility": {
            "deeptutor": ">=1.6,<3",
            "api": {
                "http_route": "1",
                "frontend_page": "1",
                "persistence_schema": "1",
                "app_connector": "1",
            },
        },
        "permissions": {"network": []},
        "dependencies": [],
        "extensions": [
            {
                "type": "http_route",
                "id": "learning_echo_http",
                "entry_point": "learning_echo.worker",
                "path": "/echo",
                "methods": ["POST"],
                "auth": "public",
            },
            {
                "type": "frontend_page",
                "id": "echo_page",
                "path": "/echo",
                "auth": "authenticated",
            },
            {
                "type": "persistence_schema",
                "id": "echo_store",
                "schema": "schemas/echo.json",
                "operations": ["read"],
            },
            {
                "type": "app_connector",
                "id": "echo_connector",
                "operations": ["import-course"],
            },
        ],
    }


def _installation(tmp_path: Path) -> PluginInstallation:
    venv_path = tmp_path / "venv"
    venv_path.mkdir(exist_ok=True)
    return PluginInstallation(
        version="1.0.0",
        artifact_path=tmp_path / "learning_echo.whl",
        artifact_sha256="0" * 64,
        venv_path=venv_path,
        python_path=Path(sys.executable),
        installed_at="2026-09-08T00:00:00+00:00",
    )


def _registry(tmp_path: Path, *, external: bool = False) -> PluginRegistry:
    manifest = parse_manifest(_raw_manifest())
    registry = PluginRegistry(
        state_path=tmp_path / "plugins.json",
        installed_distributions=[],
        deeptutor_version="1.6.0",
    )
    state = registry.state_snapshot()
    state["plugins"][manifest.id] = {
        "manifest": manifest.to_dict(),
        "installation": None if external else _installation(tmp_path).to_dict(),
        "history": [],
    }
    registry.replace_state(state)
    return registry


def _frontend_registry(tmp_path: Path, *, legacy_installation: bool = False) -> PluginRegistry:
    raw = _raw_manifest()
    raw["permissions"]["ui"] = ["sandboxed-iframe"]
    raw["extensions"][1]["manifest"] = "frontend/page.json"
    package_path = tmp_path / "package"
    frontend_path = package_path / "frontend"
    frontend_path.mkdir(parents=True)
    (frontend_path / "page.json").write_text(
        json.dumps(
            {
                "schema_version": "deeptutor.plugin-frontend-page/v1",
                "entry": "frontend/index.html",
                "assets": ["frontend/app.js", "frontend/index.html"],
            }
        ),
        encoding="utf-8",
    )
    (frontend_path / "index.html").write_text(
        '<html><body>plugin page<script src="assets/frontend/app.js"></script></body></html>',
        encoding="utf-8",
    )
    (frontend_path / "app.js").write_text("console.log('ready')", encoding="utf-8")
    (package_path / "secret.txt").write_text("secret", encoding="utf-8")

    manifest = parse_manifest(raw)
    registry = PluginRegistry(
        state_path=tmp_path / "plugins.json",
        installed_distributions=[],
        deeptutor_version="1.6.0",
    )
    installation = _installation(tmp_path)
    if not legacy_installation:
        installation = PluginInstallation(
            **{**installation.to_dict(), "package_path": package_path}
        )
    state = registry.state_snapshot()
    state["plugins"][manifest.id] = {
        "manifest": manifest.to_dict(),
        "installation": installation.to_dict(),
        "history": [],
    }
    registry.replace_state(state)
    return registry


def _record_line(name: str, payload: bytes) -> str:
    digest = base64.urlsafe_b64encode(hashlib.sha256(payload).digest()).rstrip(b"=")
    return f"{name},sha256={digest.decode('ascii')},{len(payload)}"


class _ScriptSourceParser(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.sources: list[str] = []

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        if tag == "script":
            self.sources.extend(value for key, value in attrs if key == "src" and value)


@pytest.fixture
def client() -> TestClient:
    from deeptutor.api.routers import plugins

    app = FastAPI()
    app.include_router(plugins.router, prefix="/api/plugins")
    return TestClient(app)


def _use_registry(monkeypatch: pytest.MonkeyPatch, registry: PluginRegistry) -> None:
    from deeptutor.api.routers import plugins

    monkeypatch.setattr(plugins, "_registry_factory", lambda: registry)


def test_introspection_lists_only_approved_enabled_managed_extensions(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    registry = _registry(tmp_path)
    _use_registry(monkeypatch, registry)

    assert client.get("/api/plugins/extensions").json() == {"plugins": []}

    registry.approve("org.deeptutor.learning_echo")
    body = client.get("/api/plugins/extensions").json()

    assert [plugin["id"] for plugin in body["plugins"]] == ["org.deeptutor.learning_echo"]
    assert [extension["type"] for extension in body["plugins"][0]["extensions"]] == [
        "http_route",
        "frontend_page",
        "persistence_schema",
        "app_connector",
    ]

    registry.set_enabled("org.deeptutor.learning_echo", False)
    assert client.get("/api/plugins/extensions").json() == {"plugins": []}


def test_introspection_requires_authentication(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    from deeptutor.api.routers import plugins

    _use_registry(monkeypatch, _registry(tmp_path))

    async def reject(
        *, authorization: str | None = None, dt_token: str | None = None, request=None
    ) -> None:
        raise HTTPException(status_code=401, detail="Authentication required")

    monkeypatch.setattr(plugins, "require_auth", reject)
    assert client.get("/api/plugins/extensions").status_code == 401


def test_managed_frontend_page_serves_only_declared_assets(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    registry = _frontend_registry(tmp_path)
    _use_registry(monkeypatch, registry)
    base = "/api/plugins/org.deeptutor.learning_echo/pages/echo_page/"

    assert client.get(base).status_code == 404

    registry.approve("org.deeptutor.learning_echo")
    redirect = client.get(base.rstrip("/"), follow_redirects=False)
    extensions = client.get("/api/plugins/extensions").json()["plugins"][0]["extensions"]
    page = client.get(base)
    parser = _ScriptSourceParser()
    parser.feed(page.text)
    assert parser.sources == ["assets/frontend/app.js"]
    asset = client.get(urljoin(str(page.url), parser.sources[0]))
    secret = client.get(f"{base}/assets/secret.txt")

    assert redirect.status_code == 307
    assert redirect.headers["location"] == base
    assert extensions[1]["entry_url"] == base
    assert page.status_code == 200
    assert "plugin page" in page.text
    assert page.headers["content-type"].startswith("text/html")
    assert "sandbox allow-scripts" in page.headers["content-security-policy"]
    assert page.headers["x-content-type-options"] == "nosniff"
    assert page.headers["cross-origin-resource-policy"] == "same-origin"
    assert asset.status_code == 200
    assert asset.text == "console.log('ready')"
    assert asset.headers["cross-origin-resource-policy"] == "cross-origin"
    assert secret.status_code == 404


def test_frontend_page_host_auth_and_legacy_installation_boundary(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    from deeptutor.api.routers import plugins

    auth_registry = _frontend_registry(tmp_path / "auth")
    legacy_registry = _frontend_registry(tmp_path / "legacy", legacy_installation=True)
    auth_registry.approve("org.deeptutor.learning_echo")
    legacy_registry.approve("org.deeptutor.learning_echo")
    original_auth = plugins.require_auth
    _use_registry(monkeypatch, auth_registry)

    async def reject(
        *, authorization: str | None = None, dt_token: str | None = None, request=None
    ) -> None:
        raise HTTPException(status_code=401, detail="Authentication required")

    monkeypatch.setattr(plugins, "require_auth", reject)
    assert client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page").status_code == 401

    _use_registry(monkeypatch, legacy_registry)
    monkeypatch.setattr(plugins, "require_auth", original_auth)
    assert client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page").status_code == 404


@pytest.mark.asyncio
async def test_host_auth_dependencies_receive_request_credentials(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from types import SimpleNamespace

    from deeptutor.api.routers import plugins

    request = SimpleNamespace(
        headers={"Authorization": "Bearer host-token"},
        cookies={"dt_token": "host-cookie"},
    )
    captured: dict[str, str] = {}

    async def fake_require_auth(
        *, authorization: str | None, dt_token: str | None, request=None
    ) -> str:
        captured["authorization"] = authorization or ""
        captured["dt_token"] = dt_token or ""
        return "payload"

    async def fake_require_admin(*, payload: str) -> str:
        captured["admin_payload"] = payload
        return "admin"

    monkeypatch.setattr(plugins, "require_auth", fake_require_auth)
    monkeypatch.setattr(plugins, "require_admin", fake_require_admin)

    await plugins._require_authenticated(request)
    await plugins._require_admin(request)

    assert captured == {
        "authorization": "Bearer host-token",
        "dt_token": "host-cookie",
        "admin_payload": "payload",
    }


def test_managed_route_requires_approval_and_enablement(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    registry = _registry(tmp_path)
    _use_registry(monkeypatch, registry)

    assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404

    registry.approve("org.deeptutor.learning_echo")
    assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 500

    registry.set_enabled("org.deeptutor.learning_echo", False)
    assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404


def test_external_distributions_cannot_expose_managed_http_routes(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    registry = _registry(tmp_path, external=True)
    _use_registry(monkeypatch, registry)

    assert client.get("/api/plugins/extensions").json() == {"plugins": []}
    assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404


def test_http_route_auth_is_enforced_by_host_without_forwarding_credentials(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    from deeptutor.api.routers import plugins

    registry = _registry(tmp_path)
    registry.approve("org.deeptutor.learning_echo")
    _use_registry(monkeypatch, registry)
    captured: dict[str, Any] = {}

    class StubRoute:
        def __init__(self, **kwargs: Any) -> None:
            self.extension = kwargs["manifest"].extensions[0]

        def handle(self, **kwargs: Any) -> PluginHttpResponse:
            captured.update(kwargs)
            return PluginHttpResponse(status=200, body={"ok": True})

    monkeypatch.setattr(plugins, "PluginWorkerHttpRoute", StubRoute)
    headers = {"Authorization": "Bearer secret", "Cookie": "session=secret"}

    public = client.post(
        "/api/plugins/org.deeptutor.learning_echo/echo",
        json={"message": "hello"},
        headers=headers,
    )
    assert public.status_code == 200
    assert captured == {
        "method": "POST",
        "path": "/echo",
        "query": {},
        "body": {"message": "hello"},
    }

    async def reject_auth(
        *, authorization: str | None = None, dt_token: str | None = None, request=None
    ) -> None:
        raise HTTPException(status_code=401, detail="Authentication required")

    async def allow_auth(
        *, authorization: str | None = None, dt_token: str | None = None, request=None
    ) -> str:
        return "payload"

    async def reject_admin(*, payload: object = None) -> None:
        raise HTTPException(status_code=403, detail="Admin access required")

    state = registry.state_snapshot()
    manifest = parse_manifest(state["plugins"]["org.deeptutor.learning_echo"]["manifest"])
    for policy, reject in (("authenticated", reject_auth), ("admin", reject_admin)):
        extension = manifest.extensions[0]
        object.__setattr__(extension, "auth", policy)
        state["plugins"]["org.deeptutor.learning_echo"]["manifest"] = manifest.to_dict()
        registry.replace_state(state)
        registry.approve("org.deeptutor.learning_echo")
        monkeypatch.setattr(
            plugins,
            "require_auth",
            reject_auth if policy == "authenticated" else allow_auth,
        )
        monkeypatch.setattr(plugins, "require_admin", reject_admin)
        response = client.post(
            "/api/plugins/org.deeptutor.learning_echo/echo",
            json={},
            headers=headers,
        )
        assert response.status_code == (401 if policy == "authenticated" else 403)


def test_http_route_rejects_disallowed_method_and_malformed_json(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    registry = _registry(tmp_path)
    registry.approve("org.deeptutor.learning_echo")
    _use_registry(monkeypatch, registry)

    assert client.get("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 405
    assert (
        client.post(
            "/api/plugins/org.deeptutor.learning_echo/echo",
            content=b"{invalid",
            headers={"Content-Type": "application/json"},
        ).status_code
        == 400
    )


def test_real_wheel_http_flow_uses_managed_worker_subprocess(
    client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    raw = _raw_manifest()
    raw["permissions"]["ui"] = ["sandboxed-iframe"]
    raw["extensions"][1]["manifest"] = "frontend/page.json"
    wheel_path = tmp_path / "learning_echo-1.0.0-py3-none-any.whl"
    source_root = Path(__file__).parents[2] / "docs-for-dev" / "examples" / "learning_echo"
    files = {
        "learning_echo/deeptutor.plugin.json": json.dumps(raw).encode("utf-8"),
        "learning_echo/__init__.py": (
            '"""Minimal dependency-free DeepTutor plugin worker."""\n'
        ).encode("utf-8"),
        "learning_echo/worker.py": (source_root / "learning_echo" / "worker.py").read_bytes(),
        "learning_echo/frontend/page.json": (
            source_root / "learning_echo" / "frontend" / "page.json"
        ).read_bytes(),
        "learning_echo/frontend/index.html": (
            source_root / "learning_echo" / "frontend" / "index.html"
        ).read_bytes(),
        "learning_echo/frontend/app.js": (
            source_root / "learning_echo" / "frontend" / "app.js"
        ).read_bytes(),
        "learning_echo-1.0.0.dist-info/METADATA": ("Name: learning-echo\nVersion: 1.0.0\n").encode(
            "utf-8"
        ),
        "learning_echo-1.0.0.dist-info/WHEEL": (
            "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n"
        ).encode("utf-8"),
    }
    with zipfile.ZipFile(wheel_path, "w") as archive:
        for name, payload in files.items():
            archive.writestr(name, payload)
        record_name = "learning_echo-1.0.0.dist-info/RECORD"
        archive.writestr(
            record_name,
            "\n".join([_record_line(name, payload) for name, payload in files.items()])
            + f"\n{record_name},,\n",
        )

    registry = PluginRegistry(
        state_path=tmp_path / "plugins.json",
        installed_distributions=[],
        deeptutor_version="1.6.0",
    )
    manager = PluginLifecycleManager(registry, root=tmp_path / "plugin-root")
    manager.install(wheel_path)
    registry.approve("org.deeptutor.learning_echo")
    _use_registry(monkeypatch, registry)
    record = registry.get_plugin("org.deeptutor.learning_echo")
    assert record is not None and record.installation is not None

    response = client.post(
        "/api/plugins/org.deeptutor.learning_echo/echo?tag=math",
        json={"message": "hello"},
        headers={"Authorization": "Bearer must-not-forward", "Cookie": "session=secret"},
    )

    assert response.status_code == 200
    assert response.headers["cache-control"] == "no-store"
    assert response.json() == {
        "method": "POST",
        "path": "/echo",
        "message": "hello",
        "auth": "public",
    }

    page = client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page")
    parser = _ScriptSourceParser()
    parser.feed(page.text)
    assert parser.sources == ["assets/frontend/app.js"]
    asset = client.get(urljoin(str(page.url), parser.sources[0]))

    assert page.status_code == 200
    assert "Learning Echo" in page.text
    assert "sandbox allow-scripts" in page.headers["content-security-policy"]
    assert asset.status_code == 200
    assert "restricted asset context" in asset.text


def test_lifecycle_api_uses_reviewed_snapshot_and_admin_authority(client, tmp_path, monkeypatch):
    from deeptutor.api.routers import plugins

    registry = _registry(tmp_path)
    _use_registry(monkeypatch, registry)
    info = client.get("/api/plugins/org.deeptutor.learning_echo/info").json()
    assert info["status"] == "approval-required"
    assert (
        client.post(
            "/api/plugins/org.deeptutor.learning_echo/approve", json={"snapshot_digest": "0" * 64}
        ).status_code
        == 409
    )
    approved = client.post(
        "/api/plugins/org.deeptutor.learning_echo/approve",
        json={"snapshot_digest": info["approval_digest"]},
    )
    assert approved.json()["status"] == "enabled"
    assert (
        client.post("/api/plugins/org.deeptutor.learning_echo/disable").json()["status"]
        == "disabled"
    )
    assert (
        client.post("/api/plugins/org.deeptutor.learning_echo/enable").json()["status"] == "enabled"
    )

    async def reject(request: Request):
        raise HTTPException(403, "Admin access required")

    client.app.dependency_overrides[plugins._require_admin] = reject
    try:
        assert client.post("/api/plugins/org.deeptutor.learning_echo/disable").status_code == 403
    finally:
        client.app.dependency_overrides.clear()


def test_host_identity_is_established_before_resolving_scoped_plugin_state(
    client, tmp_path, monkeypatch
):
    from deeptutor.api.routers import plugins

    registry = _registry(tmp_path)
    registry.approve("org.deeptutor.learning_echo")
    order = []

    async def authenticate(request):
        order.append("authenticated")
        return None

    def scoped_registry():
        assert order and order[0] == "authenticated"
        return registry

    class Worker:
        def __init__(self, **kwargs):
            pass

        def handle(self, **kwargs):
            return PluginHttpResponse(status=200, body={"ok": True})

    monkeypatch.setattr(plugins, "_require_authenticated", authenticate)
    monkeypatch.setattr(plugins, "_registry_factory", scoped_registry)
    monkeypatch.setattr(plugins, "PluginWorkerHttpRoute", Worker)
    assert client.post("/api/plugins/org.deeptutor.learning_echo/echo", json={}).status_code == 200