agentengine-sdk-python 0.8.2__py3-none-any.whl → 0.8.3__py3-none-any.whl

ksadk/plugins/bundle.py

@@ -0,0 +1,246 @@
+"""Resolve the plugin composition embedded in an AgentBundle v2 directory.
+
+``BundleManifest`` remains the single wire contract owned by Studio.  This
+module only creates a runtime view after the existing manifest, file digests,
+composition profile, and plugin lock have been checked against one another and
+against the selected :class:`PluginRegistry`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from pydantic import ValidationError
+
+from ksadk.plugins.bundle_security import BundleSecurityError, assert_bundle_security
+from ksadk.plugins.contracts import CompositionProfile, PluginLock
+from ksadk.plugins.resolver import PluginRegistry, PluginResolutionError, ResolvedComposition
+from ksadk.studio.contracts import BundleManifest
+
+
+class PluginBundleError(ValueError):
+    """Stable rejection while loading the plugin portion of a Bundle v2."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class ResolvedPluginBundle:
+    """Validated runtime view of existing AgentBundle v2 artifacts.
+
+    This deliberately is not another serializable bundle contract.  Providers
+    receive the already-resolved composition and the immutable resolved Agent
+    spec; they do not re-read mutable Studio state.
+    """
+
+    root: Path
+    manifest: BundleManifest
+    resolved_agent_spec: Mapping[str, Any]
+    composition: ResolvedComposition
+
+    @property
+    def bundle_digest(self) -> str:
+        return str(self.manifest.bundle_digest)
+
+
+class PluginBundleResolver:
+    """Load and cross-check the composition artifacts of an AgentBundle v2."""
+
+    def __init__(self, registry: PluginRegistry) -> None:
+        self._registry = registry
+
+    def resolve(self, root: str | Path) -> ResolvedPluginBundle:
+        bundle_root = Path(root).resolve()
+        if not bundle_root.is_dir():
+            raise PluginBundleError(
+                "plugin_bundle_unavailable",
+                f"AgentBundle directory does not exist: {bundle_root}",
+            )
+
+        manifest_payload = self._read_json(bundle_root, "manifest.json")
+        try:
+            manifest = BundleManifest.model_validate(manifest_payload)
+        except ValidationError as error:
+            raise PluginBundleError("plugin_bundle_manifest_invalid", str(error)) from error
+        if manifest.bundle_format != "agentkit.bundle/v2":
+            raise PluginBundleError(
+                "plugin_bundle_version_unsupported",
+                "PluginHost execution requires agentkit.bundle/v2",
+            )
+        if manifest.execution_profile != "composed":
+            raise PluginBundleError(
+                "plugin_bundle_legacy_execution",
+                "Bundle v2 selects legacy execution and cannot enter PluginHost",
+            )
+
+        self._verify_manifest_digest(manifest)
+        self._verify_declared_files(bundle_root, manifest)
+        try:
+            assert_bundle_security(bundle_root)
+        except BundleSecurityError as error:
+            raise PluginBundleError(
+                error.code,
+                "Plugin Bundle contains literal secret material",
+            ) from error
+
+        profile_payload = self._read_json(bundle_root, "composition-profile.json")
+        lock_payload = self._read_json(bundle_root, "plugin-lock.json")
+        agent_spec = self._read_json(bundle_root, "resolved-agent-spec.json")
+        try:
+            profile = CompositionProfile.model_validate(profile_payload)
+            embedded_lock = PluginLock.model_validate(lock_payload)
+        except ValidationError as error:
+            raise PluginBundleError("plugin_bundle_composition_invalid", str(error)) from error
+
+        try:
+            composition = self._registry.resolve(profile)
+        except PluginResolutionError as error:
+            raise PluginBundleError(error.code, str(error)) from error
+        if composition.profile_digest != manifest.composition_profile_digest:
+            raise PluginBundleError(
+                "plugin_bundle_profile_digest_mismatch",
+                "composition-profile.json does not match manifest compositionProfileDigest",
+            )
+        if embedded_lock != composition.plugin_lock:
+            raise PluginBundleError(
+                "plugin_bundle_lock_mismatch",
+                "plugin-lock.json does not match deterministic profile resolution",
+            )
+        if composition.plugin_lock_digest != manifest.plugin_lock_digest:
+            raise PluginBundleError(
+                "plugin_bundle_lock_digest_mismatch",
+                "plugin-lock.json does not match manifest pluginLockDigest",
+            )
+
+        return ResolvedPluginBundle(
+            root=bundle_root,
+            manifest=manifest,
+            resolved_agent_spec=_deep_freeze(agent_spec),
+            composition=composition,
+        )
+
+    @staticmethod
+    def _read_json(root: Path, relative: str) -> dict[str, Any]:
+        path = root / relative
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError as error:
+            raise PluginBundleError(
+                "plugin_bundle_file_missing", f"Bundle file is missing: {relative}"
+            ) from error
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            raise PluginBundleError(
+                "plugin_bundle_file_invalid", f"Bundle file is invalid: {relative}"
+            ) from error
+        if not isinstance(payload, dict):
+            raise PluginBundleError(
+                "plugin_bundle_file_invalid", f"Bundle file must be an object: {relative}"
+            )
+        return payload
+
+    @staticmethod
+    def _verify_manifest_digest(manifest: BundleManifest) -> None:
+        payload = manifest.model_dump(
+            by_alias=True,
+            exclude={"bundle_digest"},
+            exclude_none=True,
+            mode="json",
+        )
+        actual = _sha256(_canonical_json(payload))
+        if manifest.bundle_digest != actual:
+            raise PluginBundleError(
+                "plugin_bundle_digest_mismatch",
+                "manifest.json does not match its declared bundleDigest",
+            )
+
+    @staticmethod
+    def _verify_declared_files(root: Path, manifest: BundleManifest) -> None:
+        declared: set[str] = set()
+        for entry in manifest.files:
+            relative = PurePosixPath(entry.path)
+            if relative.is_absolute() or ".." in relative.parts:
+                raise PluginBundleError(
+                    "plugin_bundle_path_invalid",
+                    f"Bundle manifest contains an unsafe path: {entry.path}",
+                )
+            path = (root / Path(*relative.parts)).resolve()
+            try:
+                path.relative_to(root)
+            except ValueError as error:
+                raise PluginBundleError(
+                    "plugin_bundle_path_invalid",
+                    f"Bundle manifest path escapes its root: {entry.path}",
+                ) from error
+            try:
+                content = path.read_bytes()
+            except OSError as error:
+                raise PluginBundleError(
+                    "plugin_bundle_file_missing",
+                    f"Declared Bundle file is missing: {entry.path}",
+                ) from error
+            if len(content) != entry.size or _sha256(content) != entry.sha256:
+                raise PluginBundleError(
+                    "plugin_bundle_file_digest_mismatch",
+                    f"Declared Bundle file failed integrity check: {entry.path}",
+                )
+            declared.add(entry.path)
+
+        required = {
+            "composition-profile.json",
+            "plugin-lock.json",
+            "resolved-agent-spec.json",
+        }
+        missing = sorted(required - declared)
+        if missing:
+            raise PluginBundleError(
+                "plugin_bundle_file_missing",
+                "Bundle manifest does not declare required plugin artifacts: " + ", ".join(missing),
+            )
+        actual = {
+            path.relative_to(root).as_posix()
+            for path in root.rglob("*")
+            if path.is_file() and path.name != "manifest.json"
+        }
+        undeclared = sorted(actual - declared)
+        if undeclared:
+            raise PluginBundleError(
+                "plugin_bundle_file_undeclared",
+                "Bundle contains files outside its integrity manifest: " + ", ".join(undeclared),
+            )
+
+
+def _canonical_json(payload: Any) -> bytes:
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _sha256(payload: bytes) -> str:
+    return f"sha256:{hashlib.sha256(payload).hexdigest()}"
+
+
+def _deep_freeze(value: Any) -> Any:
+    """Prevent a Provider from mutating any nested resolved-spec value."""
+
+    if isinstance(value, dict):
+        return MappingProxyType({key: _deep_freeze(child) for key, child in value.items()})
+    if isinstance(value, list):
+        return tuple(_deep_freeze(child) for child in value)
+    return value
+
+
+__all__ = [
+    "PluginBundleError",
+    "PluginBundleResolver",
+    "ResolvedPluginBundle",
+]

ksadk/plugins/bundle_security.py

@@ -0,0 +1,167 @@
+"""Secret and local-path admission for immutable Agent Bundles.
+
+This is deliberately narrower than a generic source-code linter.  A Bundle
+may legitimately contain documentation and examples, so we inspect all
+structured deployment inputs and only use high-confidence token signatures in
+runtime source files.  The result is suitable for a build/deployment boundary:
+it prevents a resolved Bundle from becoming a durable copy of a credential
+without treating every mention of the word ``token`` as a secret.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+_SENSITIVE_KEY = re.compile(
+    r"(?:^|[_-])(?:password|passwd|api[_-]?key|access[_-]?key|secret[_-]?key|"
+    r"access[_-]?token|refresh[_-]?token|credential|private[_-]?key)(?:[_-]?ref)?$",
+    re.IGNORECASE,
+)
+_REFERENCE_PREFIXES = ("env://", "secret://", "keyring://", "vault://")
+_HIGH_CONFIDENCE_TOKENS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("private-key", re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----")),
+    ("aws-access-key", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
+    ("openai-style-key", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b")),
+    ("bearer-token", re.compile(r"\bBearer\s+[A-Za-z0-9._~+/=-]{24,}")),
+)
+_STRUCTURED_SUFFIXES = frozenset({".json", ".yaml", ".yml"})
+_RUNTIME_SOURCE_SUFFIXES = frozenset({".py", ".js", ".mjs", ".cjs", ".ts", ".tsx"})
+
+
+@dataclass(frozen=True)
+class BundleSecurityFinding:
+    """One deterministic admission finding without leaking the matched value."""
+
+    path: str
+    kind: str
+    field: str | None = None
+
+
+class BundleSecurityError(ValueError):
+    """Raised when a Bundle would persist a literal credential or host path."""
+
+    code = "bundle_secret_detected"
+
+    def __init__(self, findings: tuple[BundleSecurityFinding, ...]) -> None:
+        self.findings = findings
+        locations = ", ".join(
+            f"{finding.path}{f' ({finding.field})' if finding.field else ''}"
+            for finding in findings[:3]
+        )
+        suffix = " …" if len(findings) > 3 else ""
+        super().__init__(f"Agent Bundle contains literal secret material: {locations}{suffix}")
+
+
+def scan_bundle_security(root: str | Path) -> tuple[BundleSecurityFinding, ...]:
+    """Return high-confidence security findings for an already materialized Bundle.
+
+    Structured files receive semantic key/value inspection. Runtime source is
+    only searched for credential signatures; user Markdown and arbitrary
+    package assets are intentionally outside this detector to avoid false
+    positive build failures.
+    """
+
+    bundle_root = Path(root).resolve()
+    findings: list[BundleSecurityFinding] = []
+    for path in sorted(
+        (candidate for candidate in bundle_root.rglob("*") if candidate.is_file()),
+        key=lambda candidate: candidate.relative_to(bundle_root).as_posix(),
+    ):
+        relative = path.relative_to(bundle_root).as_posix()
+        suffix = path.suffix.lower()
+        if suffix not in _STRUCTURED_SUFFIXES and not (
+            relative.startswith("runtime/") and suffix in _RUNTIME_SOURCE_SUFFIXES
+        ):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        if suffix == ".json":
+            try:
+                payload = json.loads(text)
+            except json.JSONDecodeError:
+                findings.append(BundleSecurityFinding(relative, "invalid-structured-input"))
+                continue
+            _scan_value(payload, relative, "$", findings)
+        elif suffix in {".yaml", ".yml"}:
+            # Bundle-owned YAML is a narrow runtime launch declaration.  It
+            # has no credential-bearing fields today, but token patterns still
+            # catch accidental inline credentials without introducing a second
+            # YAML parser/security grammar.
+            _scan_text(text, relative, findings)
+        else:
+            _scan_text(text, relative, findings)
+    return tuple(findings)
+
+
+def assert_bundle_security(root: str | Path) -> None:
+    findings = scan_bundle_security(root)
+    if findings:
+        raise BundleSecurityError(findings)
+
+
+def _scan_value(
+    value: Any,
+    relative: str,
+    field: str,
+    findings: list[BundleSecurityFinding],
+) -> None:
+    if isinstance(value, dict):
+        for key, child in value.items():
+            key_text = str(key)
+            child_field = f"{field}.{key_text}"
+            normalized = key_text.replace("_", "").replace("-", "").lower()
+            # Metadata that *names* secret fields is not a secret value.
+            if normalized in {"secretfields", "credentialfields"}:
+                continue
+            if _SENSITIVE_KEY.search(key_text) and _has_literal_secret(child):
+                findings.append(
+                    BundleSecurityFinding(relative, "literal-secret-field", child_field)
+                )
+            _scan_value(child, relative, child_field, findings)
+        return
+    if isinstance(value, list):
+        for index, child in enumerate(value):
+            _scan_value(child, relative, f"{field}[{index}]", findings)
+        return
+    if isinstance(value, str):
+        _scan_text(value, relative, findings, field=field)
+        split = urlsplit(value)
+        # ``plugin://name@version`` is a pinned package reference, not URL
+        # userinfo. Only network endpoint schemes can carry credentials here.
+        if split.scheme in {"http", "https"} and (
+            split.username is not None or split.password is not None
+        ):
+            findings.append(BundleSecurityFinding(relative, "url-credentials", field))
+        if value.startswith(("/Users/", "/home/", "C:\\Users\\")):
+            findings.append(BundleSecurityFinding(relative, "local-home-path", field))
+
+
+def _has_literal_secret(value: Any) -> bool:
+    return isinstance(value, str) and bool(value) and not value.startswith(_REFERENCE_PREFIXES)
+
+
+def _scan_text(
+    text: str,
+    relative: str,
+    findings: list[BundleSecurityFinding],
+    *,
+    field: str | None = None,
+) -> None:
+    for kind, pattern in _HIGH_CONFIDENCE_TOKENS:
+        if pattern.search(text):
+            findings.append(BundleSecurityFinding(relative, kind, field))
+
+
+__all__ = [
+    "BundleSecurityError",
+    "BundleSecurityFinding",
+    "assert_bundle_security",
+    "scan_bundle_security",
+]