5b19f3b554
Completes the marketplace security model. Verification stops being advisory: a plugin only loads or migrates when its tree matches a trusted signature, and plugins are pulled from a signed shelf with anti-rollback and revocation. Enforcement (default OFF - existing deploys unchanged): - verification.py PluginVerifier, shared by the loader (verify-at-load, before plugin.py is imported) and the migration manager (verify-at-migrate, before any DDL). Fail-closed: an unsigned/tampered/wrong-key plugin does not run. - Gated by PLUGIN_REQUIRE_SIGNED. PLUGIN_DEV_TRUST_DIRS exempts named dirs but only under DEBUG/TESTING; production ignores it. - flask plugin stamp-bundled writes provenance into in-tree plugins so verify-at-load applies to bundled plugins too (image build step). - tier:core manifest guard: uninstall/disable refuse a core-tier plugin. Shelf (shelf.py): - Signed shelf-index.json (+ .sig): monotonic serial (a site refuses an older index - anti-rollback), revoked list carried across builds, per-entry version/tier/core_version for browse. Index is a browse layer only; adopt reads security-bearing fields from the verified artifact. - flask plugin shelf-build / shelf-list / adopt / audit. adopt verifies index + artifact (signature + every file hash), unpacks to staging, re-verifies, then atomically moves into place and installs+enables the closure. Refuses a downgrade without --force-downgrade. Anti-rollback serial stored in instance/shelf-state.json. - config PLUGIN_SHELF_DIR; the app only reads the folder, never speaks a network. .env.example + docs/PLUGIN-SIGNING.md document the flow. 22 tests: verifier policy (off / no-keys / signed / tampered / wrong-key / dev-exempt), verify-at-load + verify-at-migrate integration, tier guard, index sign/verify + tamper/wrong-key, serial state, revocation, version resolution, verified atomic unpack + tamper refusal. Live-smoked keygen->pack->shelf-build ->list->adopt->audit + serial guard. 1050 pass, naming green.
301 lines
11 KiB
Python
301 lines
11 KiB
Python
"""Plugin discovery and loading.
|
|
|
|
The loader reads each plugin's manifest.json before instantiating the
|
|
plugin class. Dependency sorting and contract-version compatibility
|
|
checks operate on manifests, not plugin instances. The plugin class is
|
|
imported and instantiated only after the manifest passes validation.
|
|
|
|
Failure policy (per the enforcing-plugin-contract skill):
|
|
- In dev/test (app.config.DEBUG or TESTING true): re-raise the original
|
|
exception so failures are loud.
|
|
- In production: log the failure with full context and exclude the
|
|
plugin from registration. The framework keeps booting.
|
|
"""
|
|
|
|
import importlib
|
|
import importlib.util
|
|
import json
|
|
import logging
|
|
from pathlib import Path
|
|
from typing import Dict, List, Type, Optional
|
|
|
|
from flask import Flask
|
|
from packaging.specifiers import SpecifierSet, InvalidSpecifier
|
|
from packaging.version import Version, InvalidVersion
|
|
|
|
from .base import BasePlugin
|
|
from .registry import PluginRegistry
|
|
from ..exceptions import (
|
|
PluginError,
|
|
PluginNotFoundError,
|
|
PluginContractError,
|
|
PluginVersionError,
|
|
PluginDependencyError,
|
|
)
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
class PluginLoader:
|
|
"""Discovers and loads plugins from the plugins directory."""
|
|
|
|
def __init__(self, plugins_dir: Path, registry: PluginRegistry):
|
|
self.plugins_dir = plugins_dir
|
|
self.registry = registry
|
|
self._loaded_plugins: Dict[str, BasePlugin] = {}
|
|
self._plugin_classes: Dict[str, Type[BasePlugin]] = {}
|
|
self._manifests: Dict[str, dict] = {}
|
|
# Set by PluginManager.init_app; a PluginVerifier or None (no policy).
|
|
self.verifier = None
|
|
|
|
def _is_strict_mode(self, app: Optional[Flask]) -> bool:
|
|
"""Return True if loader should re-raise instead of isolating failures."""
|
|
if app is None:
|
|
return True
|
|
return bool(app.config.get('DEBUG') or app.config.get('TESTING'))
|
|
|
|
def _handle_failure(self, app: Optional[Flask], exc: Exception, name: str) -> None:
|
|
"""In strict mode re-raise; in production log with context and continue."""
|
|
if self._is_strict_mode(app):
|
|
raise exc
|
|
logger.exception(f'Plugin {name} failed to load: {exc}')
|
|
|
|
def discover_plugins(self) -> List[str]:
|
|
"""Discover available plugins in plugins directory."""
|
|
available = []
|
|
if not self.plugins_dir.exists():
|
|
return available
|
|
|
|
for item in self.plugins_dir.iterdir():
|
|
if not item.is_dir():
|
|
continue
|
|
if (item / 'plugin.py').exists():
|
|
available.append(item.name)
|
|
|
|
return available
|
|
|
|
def load_manifest(self, name: str) -> dict:
|
|
"""Load the plugin's manifest.json.
|
|
|
|
Raises PluginNotFoundError if the manifest does not exist or is
|
|
unparseable. The result is cached.
|
|
"""
|
|
if name in self._manifests:
|
|
return self._manifests[name]
|
|
|
|
manifest_path = self.plugins_dir / name / 'manifest.json'
|
|
if not manifest_path.exists():
|
|
raise PluginNotFoundError(
|
|
f'Plugin {name} has no manifest.json at {manifest_path}',
|
|
plugin_name=name,
|
|
)
|
|
|
|
try:
|
|
with open(manifest_path) as f:
|
|
manifest = json.load(f)
|
|
except json.JSONDecodeError as e:
|
|
raise PluginContractError(
|
|
f'Plugin {name} has invalid manifest.json: {e}',
|
|
plugin_name=name,
|
|
) from e
|
|
|
|
for required in ('name', 'version', 'description'):
|
|
if not manifest.get(required):
|
|
raise PluginContractError(
|
|
f'Plugin {name} manifest.json missing required field "{required}"',
|
|
plugin_name=name,
|
|
)
|
|
|
|
if manifest['name'] != name:
|
|
raise PluginContractError(
|
|
f'Plugin directory "{name}" does not match manifest name "{manifest["name"]}"',
|
|
plugin_name=name,
|
|
)
|
|
|
|
self._manifests[name] = manifest
|
|
return manifest
|
|
|
|
def check_contract_version(self, name: str, contract_version: str) -> None:
|
|
"""Verify the plugin's core_version range includes contract_version.
|
|
|
|
Raises PluginVersionError on mismatch.
|
|
"""
|
|
manifest = self.load_manifest(name)
|
|
core_version_spec = manifest.get('core_version', '')
|
|
|
|
if not core_version_spec:
|
|
return
|
|
|
|
try:
|
|
specifier = SpecifierSet(core_version_spec)
|
|
framework_version = Version(contract_version)
|
|
except (InvalidSpecifier, InvalidVersion) as e:
|
|
raise PluginContractError(
|
|
f'Plugin {name} has invalid version specifier "{core_version_spec}": {e}',
|
|
plugin_name=name,
|
|
) from e
|
|
|
|
if framework_version not in specifier:
|
|
raise PluginVersionError(
|
|
f'Plugin {name} requires core_version {core_version_spec} '
|
|
f'but framework is at {contract_version}',
|
|
plugin_name=name,
|
|
)
|
|
|
|
def load_plugin_class(self, name: str) -> Type[BasePlugin]:
|
|
"""Import the plugin's plugin.py and return the BasePlugin subclass.
|
|
|
|
Raises PluginNotFoundError if plugin.py is missing.
|
|
Raises PluginContractError if the module has no BasePlugin subclass
|
|
or import fails.
|
|
"""
|
|
if name in self._plugin_classes:
|
|
return self._plugin_classes[name]
|
|
|
|
plugin_module_path = self.plugins_dir / name / 'plugin.py'
|
|
if not plugin_module_path.exists():
|
|
raise PluginNotFoundError(
|
|
f'Plugin {name} plugin.py not found at {plugin_module_path}',
|
|
plugin_name=name,
|
|
)
|
|
|
|
try:
|
|
spec = importlib.util.spec_from_file_location(
|
|
f'plugins.{name}.plugin', plugin_module_path,
|
|
)
|
|
module = importlib.util.module_from_spec(spec)
|
|
spec.loader.exec_module(module)
|
|
except Exception as e:
|
|
raise PluginContractError(
|
|
f'Plugin {name} import failed: {e}',
|
|
plugin_name=name,
|
|
) from e
|
|
|
|
for attr_name in dir(module):
|
|
attr = getattr(module, attr_name)
|
|
if (isinstance(attr, type)
|
|
and issubclass(attr, BasePlugin)
|
|
and attr is not BasePlugin):
|
|
self._plugin_classes[name] = attr
|
|
return attr
|
|
|
|
raise PluginContractError(
|
|
f'Plugin {name} module has no BasePlugin subclass',
|
|
plugin_name=name,
|
|
)
|
|
|
|
def load_plugin(self, name: str, app: Flask, db) -> Optional[BasePlugin]:
|
|
"""Load and instantiate a plugin.
|
|
|
|
Returns the plugin instance on success. In strict mode (dev/test),
|
|
any failure raises. In production, returns None and logs the
|
|
failure with full context.
|
|
"""
|
|
if name in self._loaded_plugins:
|
|
return self._loaded_plugins[name]
|
|
|
|
try:
|
|
from shopdb import __contract_version__
|
|
|
|
manifest = self.load_manifest(name)
|
|
self.check_contract_version(name, __contract_version__)
|
|
|
|
# verify-at-load: refuse to import plugin.py unless the tree matches
|
|
# a trusted signature (when the site enforces it). Runs BEFORE any
|
|
# plugin code is imported, so a tampered/unsigned plugin never runs.
|
|
if self.verifier is not None:
|
|
ok, reason = self.verifier.check(name)
|
|
if not ok:
|
|
raise PluginError(
|
|
f'Plugin {name} failed signature verification: {reason}',
|
|
plugin_name=name,
|
|
)
|
|
|
|
for dep in manifest.get('dependencies', []):
|
|
if not self.registry.is_enabled(dep):
|
|
raise PluginDependencyError(
|
|
f'Plugin {name} requires {dep} which is not enabled',
|
|
plugin_name=name,
|
|
)
|
|
|
|
plugin_class = self.load_plugin_class(name)
|
|
plugin = plugin_class()
|
|
plugin.init_app(app, db)
|
|
|
|
self._loaded_plugins[name] = plugin
|
|
return plugin
|
|
|
|
except PluginError as e:
|
|
self._handle_failure(app, e, name)
|
|
return None
|
|
except Exception as e:
|
|
wrapped = PluginError(
|
|
f'Unexpected failure loading plugin {name}: {e}',
|
|
plugin_name=name,
|
|
)
|
|
self._handle_failure(app, wrapped, name)
|
|
return None
|
|
|
|
def load_enabled_plugins(self, app: Flask, db) -> Dict[str, BasePlugin]:
|
|
"""Load all enabled plugins in dependency order."""
|
|
loaded = {}
|
|
|
|
enabled = self.registry.get_enabled_plugins()
|
|
sorted_plugins = self._sort_by_dependencies(enabled)
|
|
|
|
for name in sorted_plugins:
|
|
plugin = self.load_plugin(name, app, db)
|
|
if plugin:
|
|
loaded[name] = plugin
|
|
logger.info(f'Loaded plugin: {name} v{plugin.meta.version}')
|
|
|
|
return loaded
|
|
|
|
def _sort_by_dependencies(self, plugin_names: List[str]) -> List[str]:
|
|
"""Sort plugins so dependencies come first.
|
|
|
|
Reads dependencies from manifest.json directly; does not
|
|
instantiate plugin classes during sort. Detects a dependency cycle
|
|
(a back edge in the DFS) and raises PluginDependencyError rather than
|
|
looping or silently dropping a plugin.
|
|
"""
|
|
sorted_list = []
|
|
visited = set() # fully processed (post-order emitted)
|
|
visiting = set() # on the current DFS stack; a revisit here is a cycle
|
|
|
|
def visit(name):
|
|
if name in visited:
|
|
return
|
|
if name in visiting:
|
|
raise PluginDependencyError(
|
|
f'Circular plugin dependency involving "{name}"',
|
|
plugin_name=name,
|
|
)
|
|
visiting.add(name)
|
|
# Only the manifest read is tolerant; a cycle raised by a nested
|
|
# visit must propagate, so the dep recursion sits outside the guard
|
|
# (PluginDependencyError is itself a PluginError).
|
|
try:
|
|
deps = self.load_manifest(name).get('dependencies', [])
|
|
except PluginError:
|
|
deps = []
|
|
for dep in deps:
|
|
if dep in plugin_names:
|
|
visit(dep)
|
|
visiting.discard(name)
|
|
visited.add(name)
|
|
sorted_list.append(name)
|
|
|
|
for name in plugin_names:
|
|
visit(name)
|
|
|
|
return sorted_list
|
|
|
|
def get_loaded_plugin(self, name: str) -> Optional[BasePlugin]:
|
|
"""Get an already loaded plugin."""
|
|
return self._loaded_plugins.get(name)
|
|
|
|
def get_all_loaded(self) -> Dict[str, BasePlugin]:
|
|
"""Get all loaded plugins."""
|
|
return self._loaded_plugins.copy()
|