Add external plugin package verification

Author: marcofortina

README.md

@@ -262,13 +262,14 @@ automax plugins audit
 `plugins coverage` renders a builtin/external plugin matrix with category,
 remote-session, check-mode, dry-run, manual preview, diff preview and tool
 requirement coverage. `--strict` turns metadata and preview coverage failures
-into a release gate. External plugin SDK commands create, validate and package
+into a release gate. External plugin SDK commands create, validate, package and verify
 plugin sources before they are loaded with `--plugin-path`:
 
 ```bash
 automax plugins init company.echo --output ./plugins
 automax plugins check ./plugins
 automax plugins package ./plugins --output dist/company-plugins.zip
+automax plugins verify-package dist/company-plugins.zip
 automax plugins describe company.echo --plugin-path ./plugins
 ```
 

docs/concepts/plugin-system.md

@@ -59,4 +59,4 @@ The core execution engine is independent from the builtin plugin set. Future
 external plugins can be registered without changing job orchestration, state
 storage or SSH connection handling.
 
-External plugin sources can be created with `automax plugins init`, validated with `automax plugins check` and packaged with `automax plugins package`.
+External plugin sources can be created with `automax plugins init`, validated with `automax plugins check`, packaged with `automax plugins package` and verified with `automax plugins verify-package` before loading.

docs/guides/creating-plugins.md

@@ -84,14 +84,17 @@ jobs or release pipelines:
 automax plugins init company.echo --output ./plugins
 automax plugins check ./plugins
 automax plugins package ./plugins --output dist/company-plugins.zip
+automax plugins verify-package dist/company-plugins.zip
 automax plugins describe company.echo --plugin-path ./plugins
 ```
 
 `plugins init` writes a minimal plugin class with canonical metadata, parameter
 schema, examples and result fields. `plugins check` loads the external path
 without builtin plugins and fails when the metadata contract is incomplete.
 `plugins package` runs the same validation before producing a ZIP archive with
-the plugin sources and `automax-plugin.json` manifest.
+the plugin sources, `automax-plugin.json`, Automax compatibility metadata and
+per-file SHA-256 checksums. `plugins verify-package` validates that manifest and
+checksums before a package is copied into a controlled plugin directory.
 
 The packaged plugin can be unpacked into a controlled plugin directory and
 loaded with the existing `--plugin-path` option used by `run`, `validate`,

docs/reference/cli.md

@@ -214,13 +214,18 @@ automax plugins init company.echo --output ./plugins
 automax plugins check ./plugins
 automax plugins check ./plugins --format=json
 automax plugins package ./plugins --output dist/company-plugins.zip
+automax plugins package ./plugins --output dist/company-plugins.zip --automax-requires '>=0.1.0'
+automax plugins verify-package dist/company-plugins.zip
+automax plugins verify-package dist/company-plugins.zip --format=json
 automax plugins describe company.echo --plugin-path ./plugins
 ```
 
 `plugins check` loads only the external plugin path and validates the public
 metadata contract: canonical name, description, category, parameter schemas,
 examples and result fields. `plugins package` runs the same check before writing
-a ZIP archive with the plugin sources and `automax-plugin.json` manifest.
+a ZIP archive with the plugin sources, `automax-plugin.json`, Automax
+compatibility metadata and per-file SHA-256 checksums. `plugins verify-package`
+checks the manifest, canonical plugin names, file list, sizes and checksums.
 
 ## Manual commands
 

docs/reference/future-work.md

@@ -91,6 +91,13 @@ JSONL stream for external integrations:
 This could support CI summaries, dashboards, notifications or external audit
 pipelines without coupling those integrations to SQLite internals.
 
+## External plugin distribution
+
+External plugin ZIP packages include Automax compatibility metadata and per-file
+SHA-256 checksums, and can be verified with `automax plugins verify-package`.
+Future distribution work should focus on real package repositories and optional
+signature workflows, not on changing the source-loading model.
+
 ## Deploy plugins
 
 Automax already has the primitives for release-style workflows:

src/automax/cli/cli.py

@@ -43,6 +43,8 @@
     create_plugin_skeleton,
     package_external_plugin_path,
     render_plugin_check_text,
+    render_plugin_package_verify_text,
+    verify_external_plugin_package,
 )
 
 
@@ -1867,15 +1869,45 @@ def check_plugin(path: str, output_format: str) -> None:
 @click.argument("path", type=click.Path(exists=True))
 @click.option("--output", "output_path", required=True, type=click.Path(dir_okay=False), help="ZIP package path.")
 @click.option("--force", is_flag=True, help="Overwrite the package if it already exists.")
-def package_plugin(path: str, output_path: str, force: bool) -> None:
+@click.option("--automax-requires", default=">=0.1.0", show_default=True, help="Automax version range written to the package manifest.")
+def package_plugin(path: str, output_path: str, force: bool, automax_requires: str) -> None:
     """Package checked external plugin sources."""
     try:
-        output = package_external_plugin_path(path, output_path, force=force)
+        output = package_external_plugin_path(
+            path,
+            output_path,
+            force=force,
+            automax_requires=automax_requires,
+        )
     except ValueError as exc:
         raise click.ClickException(str(exc)) from exc
     click.echo(f"Wrote {output}")
 
 
+@plugins.command("verify-package")
+@click.argument("package", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+    help="Output format.",
+)
+def verify_plugin_package(package: str, output_format: str) -> None:
+    """Verify an external plugin package manifest and file checksums."""
+    try:
+        payload = verify_external_plugin_package(package)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if output_format == "json":
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        click.echo(render_plugin_package_verify_text(payload))
+    if not payload["ok"]:
+        raise click.exceptions.Exit(1)
+
+
 @plugins.command("describe")
 @click.argument("name")
 @click.option("--plugin-path", multiple=True, help="External plugin file or directory.")

src/automax/plugins/sdk.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 import zipfile
@@ -177,7 +178,37 @@ def render_plugin_check_text(payload: Dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-def package_external_plugin_path(path: str, output_path: str, *, force: bool = False) -> Path:
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _package_file_metadata(files: list[Path], root: Path) -> list[Dict[str, Any]]:
+    return [
+        {
+            "path": item.relative_to(root).as_posix(),
+            "size": item.stat().st_size,
+            "sha256": _sha256_file(item),
+        }
+        for item in files
+    ]
+
+
+def package_external_plugin_path(
+    path: str,
+    output_path: str,
+    *,
+    force: bool = False,
+    automax_requires: str = ">=0.1.0",
+) -> Path:
     """Package external plugin sources and metadata into a ZIP archive."""
     source = Path(path).expanduser().resolve()
     output = Path(output_path).expanduser().resolve()
@@ -206,12 +237,127 @@ def package_external_plugin_path(path: str, output_path: str, *, force: bool = F
     output.parent.mkdir(parents=True, exist_ok=True)
     manifest = {
         "format": "automax-external-plugin-package-v1",
+        "automax_requires": automax_requires,
         "source": str(source),
         "plugin_count": payload["checked"],
         "plugins": [plugin["name"] for plugin in payload["plugins"]],
+        "files": _package_file_metadata(files, root),
     }
     with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
         archive.writestr("automax-plugin.json", json.dumps(manifest, indent=2, sort_keys=True) + "\n")
         for item in files:
             archive.write(item, item.relative_to(root).as_posix())
     return output
+
+
+def verify_external_plugin_package(package_path: str) -> Dict[str, Any]:
+    """Verify one packaged external plugin ZIP manifest and file checksums."""
+    package = Path(package_path).expanduser().resolve()
+    failures: list[str] = []
+    manifest: Dict[str, Any] = {}
+
+    if not package.exists():
+        raise PluginRegistryError(f"plugin package not found: {package}")
+    if not package.is_file():
+        raise PluginRegistryError(f"plugin package is not a file: {package}")
+
+    try:
+        with zipfile.ZipFile(package) as archive:
+            names = archive.namelist()
+            if "automax-plugin.json" not in names:
+                failures.append("automax-plugin.json manifest is missing")
+            else:
+                try:
+                    manifest = json.loads(archive.read("automax-plugin.json").decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                    failures.append(f"automax-plugin.json is invalid: {exc}")
+
+            if manifest:
+                if manifest.get("format") != "automax-external-plugin-package-v1":
+                    failures.append("manifest format must be automax-external-plugin-package-v1")
+                plugins = manifest.get("plugins") or []
+                if not isinstance(plugins, list) or not all(isinstance(item, str) for item in plugins):
+                    failures.append("manifest plugins must be a list of plugin names")
+                    plugins = []
+                for name in plugins:
+                    if not PLUGIN_NAME_RE.match(name):
+                        failures.append(f"{name}: manifest plugin name must be canonical")
+                if manifest.get("plugin_count") != len(plugins):
+                    failures.append("manifest plugin_count does not match plugins")
+                if not manifest.get("automax_requires"):
+                    failures.append("manifest automax_requires is required")
+
+                file_entries = manifest.get("files") or []
+                if not isinstance(file_entries, list):
+                    failures.append("manifest files must be a list")
+                    file_entries = []
+                seen: set[str] = set()
+                for entry in file_entries:
+                    if not isinstance(entry, dict):
+                        failures.append("manifest file entries must be objects")
+                        continue
+                    rel = str(entry.get("path") or "")
+                    expected_hash = str(entry.get("sha256") or "")
+                    expected_size = entry.get("size")
+                    if not rel or rel.startswith("/") or ".." in Path(rel).parts:
+                        failures.append(f"invalid package file path: {rel or '<empty>'}")
+                        continue
+                    if rel in seen:
+                        failures.append(f"duplicate package file entry: {rel}")
+                        continue
+                    seen.add(rel)
+                    if rel not in names:
+                        failures.append(f"packaged file missing from archive: {rel}")
+                        continue
+                    data = archive.read(rel)
+                    if expected_hash != _sha256_bytes(data):
+                        failures.append(f"checksum mismatch: {rel}")
+                    if not isinstance(expected_size, int) or expected_size != len(data):
+                        failures.append(f"size mismatch: {rel}")
+
+                packaged_sources = sorted(
+                    name for name in names
+                    if name.endswith(".py") and not name.startswith("__pycache__/")
+                )
+                declared_sources = sorted(
+                    str(entry.get("path"))
+                    for entry in file_entries
+                    if isinstance(entry, dict) and str(entry.get("path") or "").endswith(".py")
+                )
+                if packaged_sources != declared_sources:
+                    failures.append("manifest files do not match packaged Python sources")
+    except zipfile.BadZipFile as exc:
+        failures.append(f"invalid ZIP package: {exc}")
+
+    return {
+        "ok": not failures,
+        "package": str(package),
+        "format": manifest.get("format") if manifest else None,
+        "automax_requires": manifest.get("automax_requires") if manifest else None,
+        "plugin_count": manifest.get("plugin_count") if manifest else 0,
+        "plugins": manifest.get("plugins", []) if manifest else [],
+        "files": manifest.get("files", []) if manifest else [],
+        "failure_count": len(failures),
+        "failures": failures,
+    }
+
+
+def render_plugin_package_verify_text(payload: Dict[str, Any]) -> str:
+    """Render package verification results as text."""
+    lines = ["External plugin package verification:"]
+    lines.append(f"  package:  {payload['package']}")
+    lines.append(f"  plugins:  {payload['plugin_count']}")
+    lines.append(f"  files:    {len(payload['files'])}")
+    lines.append(f"  failures: {payload['failure_count']}")
+    if payload.get("automax_requires"):
+        lines.append(f"  requires: {payload['automax_requires']}")
+    if payload["plugins"]:
+        lines.append("Plugins:")
+        for name in payload["plugins"]:
+            lines.append(f"  - {name}")
+    if payload["failures"]:
+        lines.append("Failures:")
+        for failure in payload["failures"]:
+            lines.append(f"  - {failure}")
+    lines.append(f"Result: {'OK' if payload['ok'] else 'FAILED'}")
+    return "\n".join(lines)

tests/test_documentation_and_regressions.py

@@ -474,6 +474,7 @@ def test_external_plugin_sdk_commands_are_documented():
     assert "automax plugins init" in docs
     assert "automax plugins check" in docs
     assert "automax plugins package" in docs
+    assert "automax plugins verify-package" in docs
     assert "--plugin-path" in docs
 
 

tests/test_engine.py

@@ -1970,7 +1970,46 @@ def test_plugins_init_check_package_external_sdk(tmp_path: Path):
         assert "demo_echo.py" in archive.namelist()
         manifest = json.loads(archive.read("automax-plugin.json").decode("utf-8"))
     assert manifest["format"] == "automax-external-plugin-package-v1"
+    assert manifest["automax_requires"] == ">=0.1.0"
     assert manifest["plugins"] == ["demo.echo"]
+    assert manifest["files"][0]["path"] == "demo_echo.py"
+    assert manifest["files"][0]["sha256"]
+
+    verify = runner.invoke(cli, ["plugins", "verify-package", str(package_path)])
+    assert verify.exit_code == 0, verify.output
+    assert "External plugin package verification:" in verify.output
+    assert "demo.echo" in verify.output
+    assert "Result: OK" in verify.output
+
+    json_verify = runner.invoke(cli, ["plugins", "verify-package", str(package_path), "--format", "json"])
+    assert json_verify.exit_code == 0, json_verify.output
+    verify_payload = json.loads(json_verify.output)
+    assert verify_payload["ok"] is True
+    assert verify_payload["automax_requires"] == ">=0.1.0"
+
+
+def test_plugins_verify_package_rejects_checksum_mismatch(tmp_path: Path):
+    plugin_dir = tmp_path / "plugins"
+    package_path = tmp_path / "demo-plugin.zip"
+    bad_package_path = tmp_path / "bad-plugin.zip"
+    runner = CliRunner()
+
+    assert runner.invoke(cli, ["plugins", "init", "demo.echo", "--output", str(plugin_dir)]).exit_code == 0
+    package = runner.invoke(cli, ["plugins", "package", str(plugin_dir), "--output", str(package_path)])
+    assert package.exit_code == 0, package.output
+
+    with zipfile.ZipFile(package_path) as source:
+        manifest = json.loads(source.read("automax-plugin.json").decode("utf-8"))
+        plugin_source = source.read("demo_echo.py")
+    manifest["files"][0]["sha256"] = "0" * 64
+    with zipfile.ZipFile(bad_package_path, "w") as archive:
+        archive.writestr("automax-plugin.json", json.dumps(manifest))
+        archive.writestr("demo_echo.py", plugin_source)
+
+    result = runner.invoke(cli, ["plugins", "verify-package", str(bad_package_path)])
+
+    assert result.exit_code == 1, result.output
+    assert "checksum mismatch: demo_echo.py" in result.output
 
 
 def test_plugins_check_rejects_incomplete_external_metadata(tmp_path: Path):