anna-app-core 0.2.0__py3-none-any.whl

anna_app_core/__init__.py

@@ -0,0 +1,60 @@
+"""anna-app-core: stable contract surface shared by matrix-nexus and
+anna-app-runtime-local.
+
+v0.2.0a1 — full extraction. The complete RPC dispatcher, manifest pydantic
+schemas, and helper functions now live here; matrix-nexus re-exports them
+for backward compatibility (see README.md).
+
+v0.2.0a2 — docs catch-up only (README rewrite). No API changes.
+"""
+
+from .acl import host_api_allows
+from .dispatcher import dispatch
+from .errors import HostRpcError, WindowError, WindowPermissionError
+from .manifest import (
+    AppDevConfig,
+    AppManifest,
+    ManifestExecutaRef,
+    UiBundleSection,
+    UiHostApiSpec,
+    UiManifestSection,
+    UiSize,
+    UiViewSpec,
+    WindowViewMeta,
+)
+from .protocols import WindowStoreProtocol
+from .runtime import scopes_from_manifest, select_view, view_meta
+from .versions import DISPATCHER_VERSION, SDK_VERSION
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # errors
+    "HostRpcError",
+    "WindowError",
+    "WindowPermissionError",
+    # protocols
+    "WindowStoreProtocol",
+    # acl
+    "host_api_allows",
+    # dispatcher
+    "dispatch",
+    # manifest schemas
+    "AppManifest",
+    "AppDevConfig",
+    "ManifestExecutaRef",
+    "UiBundleSection",
+    "UiHostApiSpec",
+    "UiManifestSection",
+    "UiSize",
+    "UiViewSpec",
+    "WindowViewMeta",
+    # runtime helpers
+    "select_view",
+    "scopes_from_manifest",
+    "view_meta",
+    # versions
+    "DISPATCHER_VERSION",
+    "SDK_VERSION",
+    "__version__",
+]

anna_app_core/acl.py

@@ -0,0 +1,151 @@
+"""Host-API ACL check.
+
+Accepts either a typed ``AppManifest`` (preferred — production + harness)
+or a plain ``dict`` (e.g. JSON-loaded manifest before pydantic validation).
+
+Mirrors the pre-extraction implementation in
+``matrix-nexus/src/services/anna_app_runtime_service.py::host_api_allows``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from .manifest import AppManifest
+
+
+def _ui_host_api(
+    manifest: Union[AppManifest, dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Return the ``ui.host_api`` mapping (ns -> list[method] | dict) or
+    ``None`` if the manifest has no UI section.
+
+    Note: most namespaces resolve to ``list[str]`` of allowed methods, but
+    ``agent`` is a structured dict (see ``AgentHostApiSpec``).
+    """
+    if isinstance(manifest, AppManifest):
+        if manifest.ui is None:
+            return None
+        api = manifest.ui.host_api
+        return {
+            "tools": api.tools,
+            "chat": api.chat,
+            "artifact": api.artifact,
+            "llm": api.llm,
+            "agent": api.agent.model_dump() if api.agent is not None else None,
+            "fs": api.fs,
+            "storage": api.storage,
+            "prefs": api.prefs,
+            "files": api.files,
+            "user_files": api.user_files,
+        }
+    ui = manifest.get("ui") if isinstance(manifest, dict) else None
+    if ui is None:
+        return None
+    return ui.get("host_api") or {}
+
+
+def host_api_allows(
+    manifest: Union[AppManifest, dict[str, Any]],
+    ns: str,
+    method: str,
+) -> bool:
+    """Return ``True`` iff ``ns.method`` is granted by the manifest's ACL.
+
+    `window.*` is always granted. ``tools.invoke`` and ``tools.list`` are
+    granted whenever the ``tools`` set is non-empty (per-tool gating happens
+    inside the handler). ``agent.session.*`` is granted when at least one
+    submode (``auto`` / ``fixed``) is enabled — the handler validates the
+    selected submode against the structured spec.
+    """
+    if ns == "window":
+        return True
+    api_map = _ui_host_api(manifest)
+    if api_map is None:
+        return False
+    methods = api_map.get(ns)
+    if not methods:
+        return False
+    if ns == "agent":
+        # Structured form: ``{session: {auto: bool, fixed: {client_ids:[]}}, tools: [...]}``.
+        if not method.startswith("session."):
+            return False
+        sess = methods.get("session") if isinstance(methods, dict) else None
+        if not isinstance(sess, dict):
+            return False
+        auto_on = bool(sess.get("auto"))
+        fixed_on = bool(sess.get("fixed"))
+        return auto_on or fixed_on
+    if isinstance(methods, list):
+        if "*" in methods:
+            return True
+        if method in methods:
+            return True
+    if ns == "tools" and method in ("invoke", "list"):
+        return True
+    return False
+
+
+# -----------------------------------------------------------------------------
+# Scope capability — manifest.host_capabilities
+# -----------------------------------------------------------------------------
+
+
+_ACTIONS = ("read", "write")
+_SCOPES = ("user", "app", "tool")
+
+
+def _host_caps_list(
+    manifest: Union[AppManifest, dict[str, Any]],
+) -> list[str]:
+    """Normalise ``host_capabilities`` to a flat list[str]. Tolerates dict form."""
+    if isinstance(manifest, AppManifest):
+        raw: Any = list(manifest.host_capabilities or [])
+    else:
+        raw = manifest.get("host_capabilities") if isinstance(manifest, dict) else None
+        raw = raw or []
+    if isinstance(raw, dict):
+        return [str(k) for k, v in raw.items() if v]
+    if isinstance(raw, (list, tuple)):
+        return [str(c) for c in raw]
+    return []
+
+
+def host_capability_allows_scope(
+    manifest: Union[AppManifest, dict[str, Any]],
+    scope: str,
+    action: str,
+    *,
+    cross_owner: bool = False,
+) -> bool:
+    """Return ``True`` iff the manifest grants APS access to ``(scope, action)``.
+
+    ``scope`` is one of ``user`` / ``app`` / ``tool``; ``action`` is ``read`` or
+    ``write``. ``cross_owner`` is ``True`` when the call targets a different
+    ``owner_id`` than the calling iframe (e.g. another app's ``scope=app``
+    bucket). Self-owned ``scope=app`` access stays granted by the legacy
+    ``aps.kv`` capability.
+
+    Capability strings recognised:
+
+    * ``aps.scope.admin``                       → grants everything.
+    * ``aps.scope.<scope>.<action>``            → exact match.
+    * ``aps.kv``                                → ``scope=app`` self-owned only.
+    """
+    if scope not in _SCOPES:
+        return False
+    if action not in _ACTIONS:
+        return False
+    caps = set(_host_caps_list(manifest))
+    if "aps.scope.admin" in caps:
+        return True
+    fine = f"aps.scope.{scope}.{action}"
+    if fine in caps:
+        return True
+    # Legacy: ``aps.kv`` covers self-owned scope=app reads & writes.
+    if scope == "app" and not cross_owner and ("aps.kv" in caps or "aps" in caps):
+        return True
+    return False
+
+
+__all__ = ["host_api_allows", "host_capability_allows_scope"]