nutria-plugin 0.0.1a0__py3-none-any.whl

nutria_plugin/__init__.py

@@ -0,0 +1,54 @@
+"""nutria_plugin — Nutria Plugin SDK — v0.0.1-alpha
+
+Public API
+----------
+Models:
+    PluginManifest, PluginPaths, PluginCompatibility, PluginScope, PluginRuntimeType
+
+Bundle operations:
+    load_plugin_bundle, extract_plugin_bundle, validate_zip
+
+Packaging:
+    scaffold_plugin, pack_plugin, validate_plugin_dir, PackagingError
+
+Signing:
+    generate_keypair, sign_manifest, verify_manifest, SignatureStatus
+"""
+
+__version__ = "0.0.1-alpha"
+
+
+from .manifest import (
+    PluginCompatibility,
+    PluginManifest,
+    PluginPaths,
+    PluginRuntimeType,
+    PluginScope,
+)
+from .packaging import PackagingError, pack_plugin, scaffold_plugin, validate_plugin_dir
+from .signing import SignatureStatus, generate_keypair, sign_manifest, verify_manifest
+
+__all__ = [
+    "__version__",
+    # Manifest
+    "PluginManifest",
+    "PluginPaths",
+    "PluginCompatibility",
+    "PluginScope",
+    "PluginRuntimeType",
+    # Bundle
+    "PluginBundleError",
+    "load_plugin_bundle",
+    "extract_plugin_bundle",
+    "validate_zip",
+    # Packaging
+    "PackagingError",
+    "scaffold_plugin",
+    "pack_plugin",
+    "validate_plugin_dir",
+    # Signing
+    "SignatureStatus",
+    "generate_keypair",
+    "sign_manifest",
+    "verify_manifest",
+]

nutria_plugin/bundle.py

@@ -0,0 +1,172 @@
+"""
+Plugin bundle validation and extraction.
+
+This module handles the ZIP lifecycle:
+  - validate_zip()     — check structure/size/allowlist, no I/O side-effects
+  - load_plugin_bundle() — parse and return the manifest without extracting
+  - extract_plugin_bundle() — extract into a target directory
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path, PurePosixPath
+from typing import Optional
+
+from .manifest import PluginManifest
+
+MANIFEST_FILENAME = "plugin.json"
+MAX_BUNDLE_SIZE_BYTES = 20 * 1024 * 1024   # 20 MB compressed
+MAX_UNCOMPRESSED_SIZE_BYTES = 100 * 1024 * 1024  # 100 MB total uncompressed
+
+# Allowlist — only these extensions are accepted inside a plugin ZIP.
+# Files with no extension (e.g. README, CHANGELOG) are also allowed.
+ALLOWED_EXTENSIONS = {
+    ".json",
+    ".md",
+    ".txt",
+    ".html",
+    ".htm",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".xml",
+    ".wsdl",   # SOAP specs
+    ".yaml",
+    ".yml",
+}
+
+# Kept for backwards-compatible imports; no longer used in core validation.
+BLOCKED_PATTERNS = {".py", ".js", ".ts", ".sh", ".exe", ".dll", ".so", ".whl", ".tar"}
+
+
+class PluginBundleError(Exception):
+    """Raised when a plugin ZIP is invalid, corrupt, or unsafe."""
+
+
+def _safe_zip_path(name: str) -> PurePosixPath:
+    """Return a PurePosixPath for the ZIP entry or raise PluginBundleError on path traversal.
+
+    Checks the raw string for traversal before PurePosixPath normalisation strips
+    any context (e.g. PurePosixPath("./x").parts == ("x",) — the '.' is gone).
+    """
+    if "//" in name or name.startswith("/"):
+        raise PluginBundleError(f"zip entry with absolute path is not allowed: {name!r}")
+    path = PurePosixPath(name)
+    if path.is_absolute():
+        raise PluginBundleError(f"zip entry with absolute path is not allowed: {name!r}")
+    if ".." in path.parts:
+        raise PluginBundleError(f"zip entry with path traversal is not allowed: {name!r}")
+    return path
+
+
+def validate_zip(data: bytes) -> list[str]:
+    """Validate a plugin ZIP and return a list of validation errors (empty = valid).
+
+    This does NOT extract files to disk — it only reads the ZIP in memory.
+    """
+    errors: list[str] = []
+
+    if len(data) > MAX_BUNDLE_SIZE_BYTES:
+        errors.append(
+            f"bundle exceeds max size {MAX_BUNDLE_SIZE_BYTES // (1024 * 1024)} MB"
+        )
+        return errors  # no point continuing size checks
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            names = zf.namelist()
+
+            # 1. manifest must be present at the top level
+            if MANIFEST_FILENAME not in names:
+                errors.append(f"{MANIFEST_FILENAME} not found in bundle root")
+
+            # 2. zip bomb: check total uncompressed size before any extraction
+            total_uncompressed = sum(info.file_size for info in zf.infolist())
+            if total_uncompressed > MAX_UNCOMPRESSED_SIZE_BYTES:
+                errors.append(
+                    f"bundle uncompressed content exceeds max size "
+                    f"{MAX_UNCOMPRESSED_SIZE_BYTES // (1024 * 1024)} MB"
+                )
+                return errors
+
+            for name in names:
+                try:
+                    path = _safe_zip_path(name)
+                except PluginBundleError as exc:
+                    errors.append(str(exc))
+                    continue
+
+                suffix = path.suffix.lower()
+
+                # 3. allowlist: only known-safe extensions (files with no extension are allowed)
+                if suffix and suffix not in ALLOWED_EXTENSIONS:
+                    errors.append(f"file type not allowed in plugin bundle: {name!r}")
+
+                # 4. no hidden files
+                if any(part.startswith(".") for part in path.parts):
+                    errors.append(f"hidden file/directory not allowed in plugin bundle: {name!r}")
+
+    except zipfile.BadZipFile as exc:
+        errors.append(f"invalid zip file: {exc}")
+
+    return errors
+
+
+def load_plugin_bundle(data: bytes) -> PluginManifest:
+    """Parse and return the PluginManifest from ZIP bytes without extracting to disk.
+
+    Raises:
+        PluginBundleError: if the ZIP is invalid or the manifest cannot be parsed.
+    """
+    errors = validate_zip(data)
+    if errors:
+        raise PluginBundleError("; ".join(errors))
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            raw = zf.read(MANIFEST_FILENAME)
+    except KeyError:
+        raise PluginBundleError(f"{MANIFEST_FILENAME} missing from bundle")
+    except zipfile.BadZipFile as exc:
+        raise PluginBundleError(f"invalid zip file: {exc}")
+
+    try:
+        return PluginManifest.from_json_bytes(raw)
+    except Exception as exc:
+        raise PluginBundleError(f"invalid {MANIFEST_FILENAME}: {exc}") from exc
+
+
+def extract_plugin_bundle(data: bytes, target_dir: Path) -> PluginManifest:
+    """Extract a plugin ZIP into target_dir and return the parsed manifest.
+
+    target_dir must already exist. Any existing contents are left in place;
+    the caller is responsible for cleanup on failure.
+
+    Raises:
+        PluginBundleError: if validation fails or extraction encounters path traversal.
+    """
+    manifest = load_plugin_bundle(data)  # validates first
+
+    target_dir = target_dir.resolve()
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        for info in zf.infolist():
+            if info.is_dir():
+                continue
+            safe_path = _safe_zip_path(info.filename)
+            dest = target_dir / safe_path
+            # double-check after resolving symlinks
+            try:
+                dest.resolve().relative_to(target_dir)
+            except ValueError:
+                raise PluginBundleError(
+                    f"path traversal detected during extraction: {info.filename!r}"
+                )
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(zf.read(info.filename))
+
+    return manifest

nutria_plugin/cli.py

@@ -0,0 +1,157 @@
+"""
+nutria-plugin CLI
+
+Commands:
+  keygen    Generate an ECDSA P-256 key pair for manifest signing
+  sign      Sign a plugin manifest in-place
+  new       Scaffold a new plugin directory
+  pack      Validate and pack a plugin directory into a ZIP bundle
+  validate  Validate a plugin directory without packing
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _cmd_keygen(args: argparse.Namespace) -> int:
+    from .signing import generate_keypair
+
+    out_stem = Path(args.out)
+    # Reject path traversal in the output stem
+    try:
+        resolved = out_stem.resolve()
+        cwd = Path.cwd().resolve()
+        resolved.relative_to(cwd)
+    except ValueError:
+        print(f"error: --out path must be within the current directory", file=sys.stderr)
+        return 1
+
+    private_pem, public_pem = generate_keypair()
+    priv_file = out_stem.with_suffix(".pem")
+    pub_file = out_stem.with_suffix(".pub.pem")
+    priv_file.write_text(private_pem, encoding="utf-8")
+    pub_file.write_text(public_pem, encoding="utf-8")
+    print(f"Private key: {priv_file}")
+    print(f"Public key:  {pub_file}")
+    print()
+    print("Add the public key to NUTRIA_PLUGIN_TRUSTED_KEYS:")
+    print(json.dumps([public_pem]))
+    return 0
+
+
+def _cmd_sign(args: argparse.Namespace) -> int:
+    from .signing import sign_manifest
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        print(f"error: {manifest_path} not found", file=sys.stderr)
+        return 1
+
+    key_path = Path(args.key)
+    if not key_path.exists():
+        print(f"error: {key_path} not found", file=sys.stderr)
+        return 1
+
+    private_pem = key_path.read_text(encoding="utf-8")
+    raw_dict = json.loads(manifest_path.read_text(encoding="utf-8"))
+    sig_hex = sign_manifest(raw_dict, private_pem)
+    raw_dict["signature"] = sig_hex
+    manifest_path.write_text(json.dumps(raw_dict, indent=2) + "\n", encoding="utf-8")
+    print(f"Signed: {manifest_path}")
+    return 0
+
+
+def _cmd_new(args: argparse.Namespace) -> int:
+    from .packaging import PackagingError, scaffold_plugin
+
+    target = Path(args.dir or args.id)
+    try:
+        scaffold_plugin(target, plugin_id=args.id, name=args.name)
+        print(f"Created plugin scaffold in: {target}")
+        return 0
+    except PackagingError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _cmd_pack(args: argparse.Namespace) -> int:
+    from .packaging import PackagingError, pack_plugin
+
+    plugin_dir = Path(args.dir)
+    output = Path(args.output) if args.output else None
+
+    private_pem: str | None = None
+    if args.key:
+        key_path = Path(args.key)
+        if not key_path.exists():
+            print(f"error: {key_path} not found", file=sys.stderr)
+            return 1
+        private_pem = key_path.read_text(encoding="utf-8")
+
+    try:
+        out_path = pack_plugin(plugin_dir, output, sign=bool(args.key), private_key_pem=private_pem)
+        print(f"Packed: {out_path}")
+        return 0
+    except PackagingError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    from .packaging import validate_plugin_dir
+
+    plugin_dir = Path(args.dir)
+    errors = validate_plugin_dir(plugin_dir)
+    if errors:
+        print("Validation errors:")
+        for err in errors:
+            print(f"  - {err}")
+        return 1
+    print("OK")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="nutria-plugin",
+        description="Nutria plugin SDK CLI",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_keygen = sub.add_parser("keygen", help="Generate an ECDSA P-256 key pair")
+    p_keygen.add_argument("--out", default="nutria-plugin", help="Output file stem (no extension)")
+
+    p_sign = sub.add_parser("sign", help="Sign a plugin manifest in-place")
+    p_sign.add_argument("manifest", nargs="?", default="plugin.json", help="Path to plugin.json")
+    p_sign.add_argument("--key", required=True, help="Path to private key PEM file")
+
+    p_new = sub.add_parser("new", help="Scaffold a new plugin directory")
+    p_new.add_argument("id", help="Plugin ID (e.g. my-plugin)")
+    p_new.add_argument("--name", help="Human-readable plugin name")
+    p_new.add_argument("--dir", help="Target directory (defaults to plugin ID)")
+
+    p_pack = sub.add_parser("pack", help="Validate and pack a plugin ZIP")
+    p_pack.add_argument("dir", nargs="?", default=".", help="Plugin directory to pack")
+    p_pack.add_argument("--output", "-o", help="Output ZIP path")
+    p_pack.add_argument("--key", help="Sign with this private key PEM file")
+
+    p_validate = sub.add_parser("validate", help="Validate a plugin directory")
+    p_validate.add_argument("dir", nargs="?", default=".", help="Plugin directory to validate")
+
+    args = parser.parse_args(argv)
+    handlers = {
+        "keygen": _cmd_keygen,
+        "sign": _cmd_sign,
+        "new": _cmd_new,
+        "pack": _cmd_pack,
+        "validate": _cmd_validate,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nutria_plugin/manifest.py

@@ -0,0 +1,182 @@
+"""
+Plugin manifest models for Nutria plugins.
+
+These models are the canonical schema for plugin.json and are shared between
+the SDK (for plugin authors) and the ChatBotNutralia runtime (for validation
+at install time).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from enum import Enum
+from pathlib import Path, PurePosixPath
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+_SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)"
+    r"(?:-[0-9A-Za-z.-]+)?"
+    r"(?:\+[0-9A-Za-z.-]+)?$"
+)
+
+
+def _validate_relative_path(value: str) -> str:
+    path = PurePosixPath(value)
+    if path.is_absolute():
+        raise ValueError("plugin component paths must be relative")
+    if any(part in ("", ".", "..") for part in path.parts):
+        raise ValueError("plugin component paths cannot contain empty, '.' or '..' segments")
+    return path.as_posix()
+
+
+class PluginRuntimeType(str, Enum):
+    """Runtime modes Nutria can use to expose plugin tools."""
+
+    REMOTE_MCP = "remote_mcp"
+    DECLARATIVE_API = "declarative_api"
+    OPENAPI_BRIDGE = "openapi_bridge"
+    SOAP_BRIDGE = "soap_bridge"
+
+
+class PluginScope(str, Enum):
+    """Scope where a plugin is installed."""
+
+    PLATFORM = "platform"
+    STORE = "store"
+    PERSONA = "persona"
+
+
+class PluginCompatibility(BaseModel):
+    """Compatibility gates evaluated during install."""
+
+    min_nutria_version: Optional[str] = None
+    max_nutria_version: Optional[str] = None
+
+    @field_validator("min_nutria_version", "max_nutria_version")
+    @classmethod
+    def _validate_semver(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return value
+        if not _SEMVER_RE.match(value):
+            raise ValueError("compatibility versions must use semantic versioning")
+        return value
+
+
+class PluginPaths(BaseModel):
+    """Relative paths used inside the plugin ZIP."""
+
+    connections_dir: str = "connections"
+    skills_dir: str = "skills"
+    context_docs_dir: str = "context_docs"
+    settings_schema: str = "settings.schema.json"
+    hooks_file: str = "hooks/hooks.json"
+    specs_dir: str = "specs"
+    assets_dir: str = "assets"
+
+    @field_validator(
+        "connections_dir",
+        "skills_dir",
+        "context_docs_dir",
+        "settings_schema",
+        "hooks_file",
+        "specs_dir",
+        "assets_dir",
+    )
+    @classmethod
+    def _validate_paths(cls, value: str) -> str:
+        return _validate_relative_path(value)
+
+
+class PluginManifest(BaseModel):
+    """Manifest stored in plugin.json — the single source of truth for plugin metadata."""
+
+    schema_version: str = Field(default="1.0", pattern=r"^1\.0$")
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9\-]*$", max_length=64)
+    name: str = Field(..., min_length=1, max_length=128)
+    version: str = Field(..., min_length=5, max_length=64)
+    description: str = Field(..., min_length=1, max_length=1024)
+    author: str = Field(..., min_length=1, max_length=128)
+    runtime_types: List[PluginRuntimeType] = Field(default_factory=list, min_length=1)
+    default_scope: PluginScope = PluginScope.STORE
+    compatibility: PluginCompatibility = Field(default_factory=PluginCompatibility)
+    paths: PluginPaths = Field(default_factory=PluginPaths)
+    required_secrets: List[str] = Field(default_factory=list)
+    remote_endpoints: List[str] = Field(default_factory=list)
+    capabilities: List[str] = Field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
+    homepage: Optional[str] = None
+    license: Optional[str] = None
+    signature: Optional[str] = None  # hex-encoded ECDSA-P256 DER signature
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("version")
+    @classmethod
+    def _validate_version(cls, value: str) -> str:
+        if not _SEMVER_RE.match(value):
+            raise ValueError("plugin version must use semantic versioning")
+        return value
+
+    @field_validator("required_secrets", "capabilities", "tags")
+    @classmethod
+    def _dedupe_string_lists(cls, value: List[str]) -> List[str]:
+        cleaned: List[str] = []
+        for item in value:
+            item = item.strip()
+            if item and item not in cleaned:
+                cleaned.append(item)
+        return cleaned
+
+    @field_validator("remote_endpoints")
+    @classmethod
+    def _validate_remote_endpoints(cls, value: List[str]) -> List[str]:
+        import ipaddress
+        from urllib.parse import urlparse
+
+        endpoints: List[str] = []
+        for item in value:
+            parsed = urlparse(item)
+            if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+                raise ValueError("remote_endpoints must be absolute http/https URLs")
+            # Block SSRF targets: localhost, loopback, private/link-local/reserved IP ranges.
+            hostname = parsed.hostname or ""
+            if hostname.lower() in ("localhost", "localhost.localdomain", ""):
+                raise ValueError(
+                    f"remote_endpoint {item!r} targets a private/internal address"
+                )
+            try:
+                ip = ipaddress.ip_address(hostname)
+            except ValueError:
+                ip = None  # hostname (not IP literal) — cannot statically determine
+
+            if ip is not None and (
+                ip.is_loopback or ip.is_private or ip.is_link_local or ip.is_reserved
+            ):
+                raise ValueError(
+                    f"remote_endpoint {item!r} targets a private/internal address"
+                )
+            if item not in endpoints:
+                endpoints.append(item)
+        return endpoints
+
+    @classmethod
+    def from_json_bytes(cls, raw: bytes) -> "PluginManifest":
+        """Parse a plugin manifest from raw JSON bytes."""
+        return cls.model_validate(json.loads(raw.decode("utf-8")))
+
+    @classmethod
+    def from_file(cls, path: Path) -> "PluginManifest":
+        """Load a manifest from plugin.json on disk."""
+        return cls.from_json_bytes(path.read_bytes())
+
+    def to_file(self, path: Path) -> None:
+        """Write this manifest to a plugin.json file."""
+        path.write_text(
+            json.dumps(self.model_dump(mode="json", exclude_none=True), indent=2) + "\n",
+            encoding="utf-8",
+        )

nutria_plugin/packaging.py

@@ -0,0 +1,202 @@
+"""
+Plugin scaffold, validation, and packaging helpers.
+
+nutria-plugin new    — scaffold a new plugin directory
+nutria-plugin pack   — validate and zip a plugin directory
+nutria-plugin validate — validate without packing
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+from .bundle import ALLOWED_EXTENSIONS, BLOCKED_PATTERNS, validate_zip
+from .manifest import PluginManifest, PluginPaths, PluginRuntimeType
+
+
+class PackagingError(Exception):
+    """Raised when plugin packaging fails validation."""
+
+
+SCAFFOLD_TEMPLATE = {
+    "plugin.json": lambda plugin_id, name: json.dumps(
+        {
+            "schema_version": "1.0",
+            "id": plugin_id,
+            "name": name,
+            "version": "0.1.0",
+            "description": f"{name} plugin for Nutria",
+            "author": "Your Name",
+            "runtime_types": ["declarative_api"],
+            "default_scope": "store",
+            "required_secrets": [],
+            "remote_endpoints": [],
+            "capabilities": [],
+            "tags": [],
+        },
+        indent=2,
+    )
+    + "\n",
+    "README.md": lambda plugin_id, name: f"# {name}\n\nNutria plugin for {name}.\n",
+    "hooks/hooks.json": lambda *_: json.dumps({"hooks": []}, indent=2) + "\n",
+    "settings.schema.json": lambda *_: json.dumps(
+        {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+        indent=2,
+    )
+    + "\n",
+}
+
+# Directories to create with no required placeholder files.
+SCAFFOLD_DIRS = ["connections", "skills", "context_docs", "specs", "assets"]
+
+
+def scaffold_plugin(
+    target_dir: Path,
+    plugin_id: str,
+    name: Optional[str] = None,
+    *,
+    overwrite: bool = False,
+) -> None:
+    """Create a new plugin directory with starter files.
+
+    Raises:
+        PackagingError: if target_dir already exists and overwrite is False.
+    """
+    if target_dir.exists() and not overwrite:
+        raise PackagingError(
+            f"directory {target_dir} already exists; use overwrite=True to replace"
+        )
+    name = name or plugin_id
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for rel, content_fn in SCAFFOLD_TEMPLATE.items():
+        dest = target_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content_fn(plugin_id, name), encoding="utf-8")
+    for d in SCAFFOLD_DIRS:
+        (target_dir / d).mkdir(exist_ok=True)
+
+
+def _collect_plugin_files(plugin_dir: Path) -> list[Path]:
+    """Recursively collect files to include in the plugin ZIP."""
+    files: list[Path] = []
+    for path in sorted(plugin_dir.rglob("*")):
+        if path.is_dir():
+            continue
+        rel = path.relative_to(plugin_dir)
+        # skip hidden files/dirs
+        if any(part.startswith(".") for part in rel.parts):
+            continue
+        # reject symlinks — they could point outside the plugin directory
+        if path.is_symlink():
+            raise PackagingError(
+                f"symlinks are not allowed in plugin bundles: {rel}"
+            )
+        suffix = path.suffix.lower()
+        if suffix and suffix not in ALLOWED_EXTENSIONS:
+            raise PackagingError(
+                f"file type {suffix!r} not allowed in plugin bundle: {rel}"
+            )
+        files.append(path)
+    return files
+
+
+def pack_plugin(
+    plugin_dir: Path,
+    output_path: Optional[Path] = None,
+    *,
+    sign: bool = False,
+    private_key_pem: Optional[str] = None,
+) -> Path:
+    """Validate a plugin directory and produce a ZIP bundle.
+
+    Args:
+        plugin_dir: Path to the plugin directory containing plugin.json.
+        output_path: Where to write the ZIP. Defaults to {plugin_id}-{version}.zip in the CWD.
+        sign: If True, sign the manifest before packing (requires private_key_pem).
+        private_key_pem: PEM-encoded EC private key for signing.
+
+    Returns:
+        Path to the created ZIP file.
+
+    Raises:
+        PackagingError: if validation fails.
+    """
+    manifest_path = plugin_dir / "plugin.json"
+    if not manifest_path.exists():
+        raise PackagingError(f"plugin.json not found in {plugin_dir}")
+
+    try:
+        manifest = PluginManifest.from_file(manifest_path)
+    except Exception as exc:
+        raise PackagingError(f"invalid plugin.json: {exc}") from exc
+
+    if sign:
+        if not private_key_pem:
+            raise PackagingError("private_key_pem is required when sign=True")
+        from .signing import sign_manifest
+
+        raw_dict = json.loads(manifest_path.read_text(encoding="utf-8"))
+        raw_dict["signature"] = sign_manifest(raw_dict, private_key_pem)
+        manifest_path.write_text(json.dumps(raw_dict, indent=2) + "\n", encoding="utf-8")
+        manifest = PluginManifest.from_file(manifest_path)
+
+    files = _collect_plugin_files(plugin_dir)
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for file_path in files:
+            arcname = file_path.relative_to(plugin_dir).as_posix()
+            zf.write(file_path, arcname=arcname)
+
+    data = buf.getvalue()
+    errors = validate_zip(data)
+    if errors:
+        raise PackagingError("bundle failed validation after packing: " + "; ".join(errors))
+
+    if output_path is None:
+        output_path = Path(f"{manifest.id}-{manifest.version}.zip")
+    output_path.write_bytes(data)
+    return output_path
+
+
+def validate_plugin_dir(plugin_dir: Path) -> list[str]:
+    """Validate a plugin directory without packing it.
+
+    Returns a list of errors (empty = valid).
+    """
+    errors: list[str] = []
+    manifest_path = plugin_dir / "plugin.json"
+    if not manifest_path.exists():
+        errors.append("plugin.json not found")
+        return errors
+
+    try:
+        PluginManifest.from_file(manifest_path)
+    except Exception as exc:
+        errors.append(f"invalid plugin.json: {exc}")
+
+    for path in plugin_dir.rglob("*"):
+        if path.is_dir():
+            continue
+        rel = path.relative_to(plugin_dir)
+        # Hidden files/dirs (e.g. .gitignore, .git/) are skipped by pack_plugin too;
+        # flag them only if they would cause a problem, not just because they exist.
+        if any(part.startswith(".") for part in rel.parts):
+            continue
+        if path.is_symlink():
+            errors.append(f"symlinks not allowed: {rel}")
+            continue
+        suffix = path.suffix.lower()
+        if suffix and suffix not in ALLOWED_EXTENSIONS:
+            errors.append(f"file type {suffix!r} not allowed: {rel}")
+
+    return errors

nutria_plugin/signing.py

@@ -0,0 +1,142 @@
+"""
+ECDSA-P256 plugin manifest signing and verification.
+
+Trusted public keys are configured via the NUTRIA_PLUGIN_TRUSTED_KEYS
+environment variable — a JSON array of PEM-encoded EC public keys:
+
+    NUTRIA_PLUGIN_TRUSTED_KEYS='["-----BEGIN PUBLIC KEY-----\\n..."]'
+
+CLI:
+    nutria-plugin keygen               # generate a key pair
+    nutria-plugin sign plugin.json     # sign a manifest in-place
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+class SignatureStatus(str, Enum):
+    """Result of a manifest signature verification attempt."""
+
+    VERIFIED = "verified"   # Signature present and valid against a trusted key
+    MISSING = "missing"     # No signature field, or NUTRIA_PLUGIN_TRUSTED_KEYS not set
+    INVALID = "invalid"     # Signature present but verification failed
+
+
+def generate_keypair() -> tuple[str, str]:
+    """Generate an ECDSA P-256 key pair.
+
+    Returns:
+        Tuple of (private_key_pem, public_key_pem) as strings.
+    """
+    private_key = ec.generate_private_key(ec.SECP256R1())
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).decode("utf-8")
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("utf-8")
+    return private_pem, public_pem
+
+
+def _canonical_payload(manifest_dict: dict) -> bytes:
+    """Return a deterministic JSON representation of the manifest for signing.
+
+    The 'signature' field is excluded so the payload is stable whether the
+    manifest is pre- or post-signing.
+    """
+    data = {k: v for k, v in manifest_dict.items() if k != "signature"}
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode(
+        "utf-8"
+    )
+
+
+def sign_manifest(manifest_dict: dict, private_key_pem: str) -> str:
+    """Sign a plugin manifest dict and return the hex-encoded DER signature.
+
+    The returned value should be stored in manifest_dict['signature'].
+    """
+    private_key = serialization.load_pem_private_key(
+        private_key_pem.encode("utf-8"), password=None
+    )
+    if not isinstance(private_key, ec.EllipticCurvePrivateKey):
+        raise TypeError("Private key must be an EC key")
+    return private_key.sign(_canonical_payload(manifest_dict), ec.ECDSA(hashes.SHA256())).hex()
+
+
+def _load_trusted_public_keys() -> list[ec.EllipticCurvePublicKey]:
+    """Load trusted EC public keys from NUTRIA_PLUGIN_TRUSTED_KEYS.
+
+    Returns an empty list when the env var is not set.
+    Raises ValueError when the env var is set but malformed — so a typo in
+    production fails loudly instead of silently accepting all plugins.
+    """
+    raw = os.environ.get("NUTRIA_PLUGIN_TRUSTED_KEYS", "")
+    if not raw:
+        return []
+    try:
+        pem_list: list[str] = json.loads(raw)
+        if not isinstance(pem_list, list):
+            raise ValueError("NUTRIA_PLUGIN_TRUSTED_KEYS must be a JSON array")
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise ValueError(f"NUTRIA_PLUGIN_TRUSTED_KEYS is set but invalid: {exc}") from exc
+
+    keys: list[ec.EllipticCurvePublicKey] = []
+    for pem in pem_list:
+        try:
+            key = serialization.load_pem_public_key(pem.encode("utf-8"))
+            if isinstance(key, ec.EllipticCurvePublicKey):
+                keys.append(key)
+        except Exception:
+            pass  # skip individual bad keys; caller gets fewer trusted keys
+    return keys
+
+
+def verify_manifest(manifest_dict: dict) -> SignatureStatus:
+    """Verify the ECDSA signature embedded in a plugin manifest dict.
+
+    Returns:
+        SignatureStatus.VERIFIED  – valid against at least one trusted key
+        SignatureStatus.MISSING   – no signature field, or keys not configured
+        SignatureStatus.INVALID   – signature present but verification failed
+
+    Raises:
+        ValueError: if NUTRIA_PLUGIN_TRUSTED_KEYS is set but malformed.
+    """
+    sig_hex: Optional[str] = manifest_dict.get("signature")
+    if not sig_hex:
+        return SignatureStatus.MISSING
+
+    try:
+        sig_der = bytes.fromhex(sig_hex)
+    except ValueError:
+        return SignatureStatus.INVALID
+
+    payload = _canonical_payload(manifest_dict)
+    trusted_keys = _load_trusted_public_keys()  # may raise ValueError
+
+    if not trusted_keys:
+        return SignatureStatus.MISSING
+
+    for key in trusted_keys:
+        try:
+            key.verify(sig_der, payload, ec.ECDSA(hashes.SHA256()))
+            return SignatureStatus.VERIFIED
+        except InvalidSignature:
+            continue
+        except Exception:
+            continue
+
+    return SignatureStatus.INVALID

nutria_plugin-0.0.1a0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: nutria-plugin
+Version: 0.0.1a0
+Summary: SDK for building, validating, signing, and packaging Nutria plugins
+Project-URL: Homepage, https://github.com/AlRos14/nutria-plugin-sdk
+Project-URL: Repository, https://github.com/AlRos14/nutria-plugin-sdk
+Project-URL: Changelog, https://github.com/AlRos14/nutria-plugin-sdk/blob/main/CHANGELOG.md
+Author-email: Nutria <dev@nutria.ai>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: lxml>=4.9
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nutria-plugin SDK
+
+SDK for building, validating, signing, and packaging Nutria plugins.
+
+## Install
+
+```bash
+pip install nutria-plugin
+# or with uv
+uv add nutria-plugin
+```
+
+## Quickstart
+
+### 1. Scaffold a new plugin
+
+```bash
+nutria-plugin new my-workspace-plugin --name "My Workspace Plugin"
+```
+
+This creates:
+
+```
+my-workspace-plugin/
+  plugin.json          # manifest — edit this
+  README.md
+  connections/         # one JSON file per connection
+  skills/              # SKILL.md files
+  context_docs/        # Markdown docs injected into persona prompts
+  specs/               # OpenAPI/WSDL specs
+  hooks/hooks.json     # declarative hooks
+  settings.schema.json # config schema shown in admin UI
+```
+
+### 2. Edit plugin.json
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "my-workspace-plugin",
+  "name": "My Workspace Plugin",
+  "version": "0.1.0",
+  "description": "Connects Nutria to My Workspace tool",
+  "author": "Your Name",
+  "runtime_types": ["declarative_api"],
+  "required_secrets": ["API_KEY"],
+  "remote_endpoints": ["https://api.myworkspace.com"]
+}
+```
+
+### 3. Validate
+
+```bash
+nutria-plugin validate .
+# OK
+```
+
+### 4. Pack
+
+```bash
+nutria-plugin pack . --output my-workspace-plugin-0.1.0.zip
+# Packed: my-workspace-plugin-0.1.0.zip
+```
+
+### 5. Sign (optional)
+
+Generate a key pair once:
+
+```bash
+nutria-plugin keygen --out my-signing-key
+# Private key: my-signing-key.pem
+# Public key:  my-signing-key.pub.pem
+```
+
+Sign before packing:
+
+```bash
+nutria-plugin sign plugin.json --key my-signing-key.pem
+nutria-plugin pack . --output my-workspace-plugin-0.1.0.zip
+```
+
+Or sign during pack:
+
+```bash
+nutria-plugin pack . --key my-signing-key.pem --output my-workspace-plugin-0.1.0.zip
+```
+
+Configure the Nutria instance to trust your public key:
+
+```bash
+export NUTRIA_PLUGIN_TRUSTED_KEYS='["-----BEGIN PUBLIC KEY-----\n..."]'
+```
+
+## Python API
+
+```python
+from nutria_plugin import (
+    PluginManifest,
+    load_plugin_bundle,
+    extract_plugin_bundle,
+    validate_zip,
+    scaffold_plugin,
+    pack_plugin,
+    validate_plugin_dir,
+    generate_keypair,
+    sign_manifest,
+    verify_manifest,
+    SignatureStatus,
+)
+
+# Parse a manifest
+manifest = PluginManifest.from_file(Path("plugin.json"))
+
+# Load from ZIP bytes
+manifest = load_plugin_bundle(zip_bytes)
+
+# Extract to disk
+manifest = extract_plugin_bundle(zip_bytes, target_dir)
+
+# Sign and verify
+private_pem, public_pem = generate_keypair()
+sig = sign_manifest(manifest.model_dump(), private_pem)
+status = verify_manifest(manifest.model_dump())
+assert status == SignatureStatus.VERIFIED
+```
+
+## Plugin ZIP format
+
+| Path | Description |
+|------|-------------|
+| `plugin.json` | Manifest (required) |
+| `README.md` | Human-readable description |
+| `connections/*.json` | Connection definitions |
+| `skills/<name>/SKILL.md` | Skill instructions |
+| `context_docs/*.md` | Docs injected into persona prompts |
+| `specs/openapi.json` | OpenAPI spec (for `openapi_bridge` runtime) |
+| `specs/service.wsdl` | WSDL spec (for `soap_bridge` runtime) |
+| `hooks/hooks.json` | Declarative hooks |
+| `settings.schema.json` | JSON Schema for configuration |
+| `assets/icon.png` | Plugin icon |
+
+### Security rules
+
+- No executable files (`.py`, `.js`, `.sh`, etc.) allowed in the ZIP.
+- No hidden files or directories.
+- No absolute paths or path traversal in ZIP entries.
+- Maximum bundle size: 20 MB.
+- Secrets are **never** stored in the ZIP — they are configured after install.
+
+## Runtime types
+
+| Value | Description |
+|-------|-------------|
+| `remote_mcp` | Plugin connects to a separately deployed MCP server |
+| `declarative_api` | Plugin uses declarative connection JSON files (no server needed) |
+| `openapi_bridge` | Nutria auto-generates tools from an OpenAPI/Swagger spec |
+| `soap_bridge` | Nutria auto-generates tools from a WSDL/SOAP spec |
+
+## License
+
+MIT

nutria_plugin-0.0.1a0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nutria_plugin/__init__.py,sha256=bdQuSU54aLpoDOsXcgsR3ZfdpspSEfynOsIpqbHhbIY,1239
+nutria_plugin/bundle.py,sha256=-2tYptl-rC-xlzr3rOMmd6UtS3JWryASjeaxdYNhh8s,6019
+nutria_plugin/cli.py,sha256=yrQbdRAuNIUg8exxQgPPhnWAex3oo1rl9A63iuebKNs,5223
+nutria_plugin/manifest.py,sha256=4sGMxDQxVfFMGYddY2KiPlh3pedwN_Bu44GlXyaR3H0,6339
+nutria_plugin/packaging.py,sha256=g2j-5BDIgFhCgobJtlflZk0v_XXgPlAqDBj2r2MBVwo,6678
+nutria_plugin/signing.py,sha256=5xUqTVSz-0txPI6fvOEXtPhLSSTcCSkgUN9fZELP47c,5055
+nutria_plugin-0.0.1a0.dist-info/METADATA,sha256=Hi4EAjbMqsO9tbZer0shKWgyjQYavO52xVSsTC9bdyc,4574
+nutria_plugin-0.0.1a0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nutria_plugin-0.0.1a0.dist-info/entry_points.txt,sha256=k1YvyaEBQOjCTCjDlKaw2t_f_HL38tkQMPNbFxnn7mg,57
+nutria_plugin-0.0.1a0.dist-info/RECORD,,

nutria_plugin-0.0.1a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nutria_plugin-0.0.1a0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nutria-plugin = nutria_plugin.cli:main