nutria-plugin 0.0.1a0__tar.gz

nutria_plugin-0.0.1a0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build packages
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nutria_plugin-0.0.1a0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.zip
+*.pem
+*.pub.pem

nutria_plugin-0.0.1a0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to `nutria-plugin` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.0.1-alpha] — 2025-03-08
+
+Initial alpha release. API and file format are not yet stable.
+
+### Added
+
+**Manifest model (`manifest.py`)**
+- `PluginManifest` — Pydantic v2 model for `plugin.json` with strict validation
+- Fields: `id`, `name`, `version`, `description`, `author`, `runtime_types`,
+  `default_scope`, `compatibility`, `paths`, `required_secrets`,
+  `remote_endpoints`, `capabilities`, `tags`, `homepage`, `license`, `signature`
+- `PluginRuntimeType` enum: `remote_mcp`, `declarative_api`, `openapi_bridge`, `soap_bridge`
+- `PluginScope` enum: `platform`, `store`, `persona`
+- `PluginCompatibility` model with semver-validated `min_nutria_version` / `max_nutria_version`
+- `PluginPaths` model for overriding default component paths
+- `PluginManifest.from_file()`, `from_json_bytes()`, `to_file()` helpers
+
+**Bundle operations (`bundle.py`)**
+- `load_plugin_bundle(data: bytes) -> PluginManifest` — parse and validate a plugin ZIP
+- `extract_plugin_bundle(data: bytes, target_dir: Path) -> PluginManifest` — safe extraction
+- `validate_zip(data: bytes) -> list[str]` — non-extracting ZIP validation
+- `PluginBundleError` exception
+- Decompression bomb guard: 100 MB uncompressed size limit
+- Extension allowlist: `.json .md .yaml .yml .txt .png .jpg .jpeg .svg .ico .pdf .wsdl .xsd .xml .csv`
+- Path traversal prevention via `PurePosixPath` normalization
+- Maximum ZIP size: 20 MB
+
+**Packaging (`packaging.py`)**
+- `scaffold_plugin(plugin_id, name, target_dir)` — create standard plugin directory
+- `pack_plugin(plugin_dir, output_path, sign, private_key_pem) -> Path` — validate and pack
+- `validate_plugin_dir(plugin_dir) -> list[str]` — directory validation (hidden files skipped)
+- `PackagingError` exception
+- Symlink rejection at pack time
+- Hidden file skipping (consistent between `validate_plugin_dir` and `pack_plugin`)
+
+**Signing (`signing.py`)**
+- `generate_keypair() -> tuple[str, str]` — ECDSA P-256 key pair generation
+- `sign_manifest(manifest: dict, private_key_pem: str) -> str` — sign and return hex DER signature
+- `verify_manifest(manifest: dict) -> SignatureStatus` — verify against `NUTRIA_PLUGIN_TRUSTED_KEYS`
+- `SignatureStatus` enum: `VERIFIED`, `UNSIGNED`, `INVALID`, `UNTRUSTED`, `MISSING`
+- Canonical payload serialization (sorted keys, no `signature` field, no whitespace)
+- `NUTRIA_PLUGIN_TRUSTED_KEYS` env var for trusted public key list
+
+**CLI (`cli.py`)**
+- `nutria-plugin new <id>` — scaffold plugin directory
+- `nutria-plugin validate [dir]` — validate plugin directory
+- `nutria-plugin pack [dir]` — validate and pack to ZIP
+- `nutria-plugin sign [manifest] --key <pem>` — sign manifest in-place
+- `nutria-plugin keygen [--out <stem>]` — generate ECDSA P-256 key pair
+- `--key` flag on `pack` for inline sign-and-pack
+- `--output`/`-o` flag on `pack` for custom output path
+
+**Documentation**
+- `docs/index.md` — overview and navigation
+- `docs/quickstart.md` — first plugin in 5 minutes
+- `docs/manifest.md` — complete `plugin.json` field reference
+- `docs/connection-types.md` — all 4 runtime types with annotated examples
+- `docs/skill-format.md` — `SKILL.md` frontmatter schema and authoring guide
+- `docs/security.md` — signing, trust policies, ZIP safety, secrets
+- `docs/cli.md` — all CLI commands and flags
+- `docs/python-api.md` — Python API reference
+
+**Security hardening**
+- SSRF protection: `remote_endpoints` blocks loopback, private, link-local, reserved IPs
+- Decompression bomb: 100 MB limit on `ZipInfo.file_size` before extraction
+- Symlink blocking: `PackagingError` raised on any symlink in plugin source
+- Extension allowlist (not blocklist)
+- CLI `keygen --out` path traversal prevention (output path must be within CWD)
+- `_safe_zip_path`: checks `".." in path.parts` on normalized `PurePosixPath`
+
+### Notes
+
+- This is an alpha release. Manifest schema, connection file format, and
+  Python API may change before `0.1.0`.
+- `declarative_api` connection file format is not yet formally versioned.
+- WSDL/OpenAPI bridge tool name conventions are established but the bridge
+  runtime is implemented in the ChatBotNutralia host, not this package.

nutria_plugin-0.0.1a0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,161 @@
+# 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/docs/cli.md

@@ -0,0 +1,189 @@
+# CLI Reference
+
+The `nutria-plugin` CLI is the primary tool for plugin development.
+
+## Installation
+
+```bash
+uv add nutria-plugin
+# or
+pip install nutria-plugin
+```
+
+---
+
+## `nutria-plugin new` — Scaffold a plugin
+
+Create a new plugin directory with the standard structure.
+
+```bash
+nutria-plugin new <id> [--name <display-name>] [--dir <target-dir>]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `id` | Plugin ID (lowercase, hyphens allowed, e.g. `my-plugin`) |
+| `--name` | Display name. Defaults to title-cased `id` |
+| `--dir` | Target directory. Defaults to `<id>/` in the current directory |
+
+**Examples:**
+
+```bash
+# Scaffold in ./my-crm-plugin/
+nutria-plugin new my-crm-plugin
+
+# Custom name and directory
+nutria-plugin new my-crm-plugin --name "My CRM Plugin" --dir ~/plugins/my-crm
+```
+
+**Created structure:**
+
+```
+<dir>/
+  plugin.json          # pre-filled manifest
+  README.md
+  connections/         # empty — add your connection JSON files
+  skills/              # empty — add your SKILL.md subdirectories
+  context_docs/        # empty — add your Markdown reference docs
+  specs/               # empty — add OpenAPI/WSDL files
+  hooks/hooks.json     # empty hooks array
+  settings.schema.json # empty JSON Schema
+  assets/              # empty
+```
+
+---
+
+## `nutria-plugin validate` — Validate a plugin
+
+Validate a plugin directory (does not pack).
+
+```bash
+nutria-plugin validate [<dir>]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `dir` | Plugin directory to validate. Defaults to `.` |
+
+**Exit codes:** `0` = valid, `1` = one or more errors found.
+
+**Output:**
+
+```bash
+$ nutria-plugin validate my-plugin/
+OK
+
+$ nutria-plugin validate broken-plugin/
+Validation errors:
+  - invalid plugin.json: version must use semantic versioning
+  - invalid plugin.json: remote_endpoints[0] targets a private/internal address
+```
+
+Validation checks:
+- All `plugin.json` fields (see [manifest.md](manifest.md))
+- Required files present (`plugin.json`, at least one connection or skill)
+- No hidden files in the directory
+- No symlinks
+
+---
+
+## `nutria-plugin pack` — Validate and pack a ZIP
+
+Validate the plugin and produce a distributable ZIP archive.
+
+```bash
+nutria-plugin pack [<dir>] [--output <path>] [--key <pem-file>]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `dir` | Plugin directory to pack. Defaults to `.` |
+| `--output`, `-o` | Output ZIP path. Defaults to `<id>-<version>.zip` in the current directory |
+| `--key` | Path to a PEM private key file. If provided, the manifest is signed before packing |
+
+**Examples:**
+
+```bash
+# Pack to default name (my-plugin-0.1.0.zip)
+nutria-plugin pack my-plugin/
+
+# Custom output path
+nutria-plugin pack my-plugin/ --output dist/my-plugin-0.1.0.zip
+
+# Sign and pack
+nutria-plugin pack my-plugin/ --key my-signing-key.pem --output dist/my-plugin-0.1.0.zip
+```
+
+**What pack does:**
+1. Runs full validation — aborts on any error
+2. Collects all files, skipping hidden files and checking extensions
+3. Rejects symlinks
+4. Writes a ZIP with stored (non-compressed) entries and safe paths
+5. Optionally signs the manifest before writing
+
+---
+
+## `nutria-plugin sign` — Sign a manifest in-place
+
+Sign an existing `plugin.json` file. Modifies the file by adding or updating
+the `signature` field.
+
+```bash
+nutria-plugin sign [<manifest>] --key <pem-file>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `manifest` | Path to `plugin.json`. Defaults to `plugin.json` in the current directory |
+| `--key` | Path to the PEM private key file (required) |
+
+**Example:**
+
+```bash
+nutria-plugin sign plugin.json --key my-signing-key.pem
+```
+
+Signing does not pack — run `nutria-plugin pack` after signing to produce
+the distributable ZIP.
+
+---
+
+## `nutria-plugin keygen` — Generate a signing key pair
+
+Generate an ECDSA P-256 key pair for plugin signing.
+
+```bash
+nutria-plugin keygen [--out <stem>]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `--out` | Output file stem. Defaults to `nutria-plugin`. Output path must be within the current directory |
+
+**Output files:**
+
+| File | Contents |
+|------|----------|
+| `<stem>.pem` | PEM-encoded private key — keep secret, never commit |
+| `<stem>.pub.pem` | PEM-encoded public key — distribute to Nutria instances |
+
+**Example:**
+
+```bash
+nutria-plugin keygen --out acme-publisher
+# Private key: acme-publisher.pem
+# Public key:  acme-publisher.pub.pem
+```
+
+**Security note:** The output path is resolved and must be within the current
+working directory. Path traversal in `--out` is rejected.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Validation error, signing error, or unexpected failure |
+| `2` | CLI usage error (invalid arguments) |