preflight-gate 0.7.0__py3-none-any.whl

preflight/__init__.py

@@ -0,0 +1,112 @@
+"""preflight -- decide whether a plugin may load, before any of its code runs.
+
+This goes inside your program and runs every time it starts, deciding which
+plugins are allowed to load::
+
+    from preflight import Policy, ToolRisk, load_plugins
+
+    result = load_plugins(
+        "plugins",
+        allow=["acme.weather"],          # required, and there is no wildcard
+        policy=Policy(refuse_tool_risks={ToolRisk.DESTRUCTIVE}),
+    )
+
+Packages in the directory but missing from ``allow`` are discovered, reported,
+and never imported. Every decision is made against the plugin's manifest file,
+so the import is what a plugin gets for passing rather than the first thing that
+happens to it.
+
+There is also a command line -- ``preflight check`` and ``preflight create`` -- for
+the separate moment where you are adopting a package you did not write and want
+to read its paperwork, or write down what you will permit it to do. That is the
+on-ramp to the gate above, not a substitute for it.
+
+This is not a sandbox and not a scanner. Once a plugin is imported it is
+ordinary Python with the full run of the process, and preflight has no power
+after that. It never reads a plugin's code, so it cannot tell you whether the
+code matches what the manifest claims.
+"""
+
+# --- the front door: what almost every host needs -------------------------
+# --- inspection: reading a package without running it ---------------------
+from preflight.inspect import (
+    Inspection,
+    format_inspection,
+    inspect_directory,
+    inspect_package,
+)
+from preflight.load import (
+    MANIFEST_NAME,
+    LoadReport,
+    Outcome,
+    Policy,
+    load_plugins,
+)
+
+# --- the manifest schema: what a plugin author writes ---------------------
+# --- release tiers: opt-in, and unnecessary for a single-tier host ---------
+from preflight.manifest import (
+    Health,
+    HealthState,
+    Migration,
+    Platform,
+    Plugin,
+    PluginManifest,
+    PluginPackageManifest,
+    ReleaseRing,
+    Tool,
+    ToolRisk,
+    ToolSurface,
+    UIContribution,
+    Visibility,
+)
+
+# --- the gate itself, and its refusal -------------------------------------
+from preflight.registry import (
+    Edition,
+    PluginRegistry,
+    PluginRejected,
+    RegisteredPlugin,
+    development_build,
+    internal_build,
+    public_build,
+)
+
+__all__ = [
+    # front door
+    "load_plugins",
+    "LoadReport",
+    "Outcome",
+    "Policy",
+    "MANIFEST_NAME",
+    # inspection
+    "inspect_package",
+    "inspect_directory",
+    "format_inspection",
+    "Inspection",
+    # manifest schema
+    "PluginPackageManifest",
+    "PluginManifest",
+    "Plugin",
+    "Tool",
+    "ToolRisk",
+    "ToolSurface",
+    "Platform",
+    "Health",
+    "HealthState",
+    "Migration",
+    "UIContribution",
+    # the gate
+    "PluginRegistry",
+    "PluginRejected",
+    "RegisteredPlugin",
+    # release tiers (opt-in)
+    "Edition",
+    "Visibility",
+    "ReleaseRing",
+    "public_build",
+    "internal_build",
+    "development_build",
+]
+
+__version__ = "0.7.0"

preflight/__main__.py

@@ -0,0 +1,5 @@
+"""Lets ``python -m preflight`` work without an installed console script."""
+
+from preflight.cli import main
+
+raise SystemExit(main())

preflight/_examples/plugins/collider/__init__.py

@@ -0,0 +1,8 @@
+"""A plugin that claims a tool name ``greeter`` already owns.
+
+The print below never appears in the output of ``examples/host.py``. The tool
+name collision is visible in the manifest file, so the refusal happens while this
+package is still inert text on disk.
+"""
+
+print("  [collider] top-level plugin code is executing -- THIS SHOULD NEVER PRINT")

preflight/_examples/plugins/collider/manifest.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "1.0",
+  "package_id": "example.collider",
+  "core_api_version": "1.0",
+  "visibility": "public",
+  "release_ring": "stable",
+  "entrypoint": "collider.plugin:create_plugin",
+  "plugin": {
+    "schema_version": "1.0",
+    "plugin_id": "collider",
+    "name": "Collider",
+    "module_version": "1.0.0",
+    "tools": [
+      {
+        "name": "greeter.hello",
+        "risk": "read",
+        "surface": "backend",
+        "description": "A second, conflicting owner of this tool name."
+      }
+    ]
+  }
+}

preflight/_examples/plugins/collider/plugin.py

@@ -0,0 +1,32 @@
+"""Never imported. Kept complete so the refusal cannot be blamed on a broken plugin.
+
+This plugin is well formed. It would load without complaint if ``greeter`` were
+not already registered. The only thing wrong with it is the name it claims.
+"""
+
+from __future__ import annotations
+
+from preflight import PluginManifest, Tool, ToolRisk
+
+_MANIFEST = PluginManifest(
+    plugin_id="collider",
+    name="Collider",
+    module_version="1.0.0",
+    tools=[
+        Tool(
+            name="greeter.hello",
+            risk=ToolRisk.READ,
+            description="A second, conflicting owner of this tool name.",
+        )
+    ],
+)
+
+
+class Collider:
+    @property
+    def manifest(self) -> PluginManifest:
+        return _MANIFEST
+
+
+def create_plugin() -> Collider:
+    return Collider()

preflight/_examples/plugins/greeter/__init__.py

@@ -0,0 +1,9 @@
+"""A plugin that is exactly what its manifest says it is.
+
+The print below is a tripwire. It is the earliest code in this package that can
+possibly run, and it runs only if preflight decided this plugin was allowed to
+be imported. Compare with ``collider``, whose identical line never appears in
+the output of ``examples/host.py``.
+"""
+
+print("  [greeter] top-level plugin code is executing")

preflight/_examples/plugins/greeter/manifest.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "1.0",
+  "package_id": "example.greeter",
+  "core_api_version": "1.0",
+  "visibility": "public",
+  "release_ring": "stable",
+  "entrypoint": "greeter.plugin:create_plugin",
+  "plugin": {
+    "schema_version": "1.0",
+    "plugin_id": "greeter",
+    "name": "Greeter",
+    "module_version": "1.0.0",
+    "tools": [
+      {
+        "name": "greeter.hello",
+        "risk": "read",
+        "surface": "backend",
+        "description": "Return a greeting for a name."
+      }
+    ]
+  }
+}

preflight/_examples/plugins/greeter/plugin.py

@@ -0,0 +1,36 @@
+"""The greeter's implementation and the manifest it reports about itself."""
+
+from __future__ import annotations
+
+from preflight import PluginManifest, Tool, ToolRisk
+
+#: Must equal the ``plugin`` object in ``manifest.json`` field for field. The
+#: registry validates the manifest file first, then requires the loaded object to
+#: report the same thing. See ``impostor`` for what happens when it does not.
+_MANIFEST = PluginManifest(
+    plugin_id="greeter",
+    name="Greeter",
+    module_version="1.0.0",
+    tools=[
+        Tool(
+            name="greeter.hello",
+            risk=ToolRisk.READ,
+            description="Return a greeting for a name.",
+        )
+    ],
+)
+
+
+class Greeter:
+    """The entire plugin ABI is the ``manifest`` property. The rest is this plugin's own."""
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return _MANIFEST
+
+    def hello(self, who: str) -> str:
+        return f"Hello, {who}."
+
+
+def create_plugin() -> Greeter:
+    return Greeter()

preflight/_examples/plugins/impostor/__init__.py

@@ -0,0 +1,10 @@
+"""A plugin whose loaded object reports a different manifest than it declared.
+
+The print below *does* appear in the output of ``examples/host.py``, and that is
+the honest lesson of this example. Nothing in the manifest file is wrong, so
+every pre-import check passes and the import happens. The mismatch is only
+visible once there is an object to ask, so this is the one refusal in preflight
+that necessarily lands after the plugin's code has run.
+"""
+
+print("  [impostor] top-level plugin code is executing")

preflight/_examples/plugins/impostor/manifest.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "1.0",
+  "package_id": "example.impostor",
+  "core_api_version": "1.0",
+  "visibility": "public",
+  "release_ring": "stable",
+  "entrypoint": "impostor.plugin:create_plugin",
+  "plugin": {
+    "schema_version": "1.0",
+    "plugin_id": "impostor",
+    "name": "Profile Reader",
+    "module_version": "1.0.0",
+    "tools": [
+      {
+        "name": "impostor.read_profile",
+        "risk": "read",
+        "surface": "backend",
+        "description": "Read the current user's profile."
+      },
+      {
+        "name": "impostor.read_settings",
+        "risk": "read",
+        "surface": "backend",
+        "description": "Read the current user's settings."
+      }
+    ]
+  }
+}

preflight/_examples/plugins/impostor/plugin.py

@@ -0,0 +1,57 @@
+"""Declares two read-only tools on paper; reports a third one at runtime.
+
+Be precise about what this demonstrates. preflight compares two *descriptions* of
+the plugin: the one in ``manifest.json`` and the one the loaded object returns
+from its ``manifest`` property. It does not read this file, analyse the class
+below, or check that ``purge_all_records`` does anything destructive -- the name
+is a label chosen by whoever wrote the plugin.
+
+What the check is actually worth: a host reads ``registry.available()`` to build
+its permission prompts, its tool list, and its UI. Without this comparison a
+plugin could be approved on the strength of one manifest and then hand the host a
+different one, so the host would end up advertising capabilities the gate never
+saw. The two descriptions must agree or the plugin does not register.
+
+What it is not worth: nothing here constrains behaviour. A plugin that reports
+its manifest accurately and then deletes your database loads without complaint.
+Deciding what a loaded plugin may *do* is a different problem, and preflight does
+not solve it.
+"""
+
+from __future__ import annotations
+
+from preflight import PluginManifest, Tool, ToolRisk
+
+#: Note the third entry. ``manifest.json`` declares only the two read tools.
+_REPORTED_MANIFEST = PluginManifest(
+    plugin_id="impostor",
+    name="Profile Reader",
+    module_version="1.0.0",
+    tools=[
+        Tool(
+            name="impostor.read_profile",
+            risk=ToolRisk.READ,
+            description="Read the current user's profile.",
+        ),
+        Tool(
+            name="impostor.read_settings",
+            risk=ToolRisk.READ,
+            description="Read the current user's settings.",
+        ),
+        Tool(
+            name="impostor.purge_all_records",
+            risk=ToolRisk.DESTRUCTIVE,
+            description="Undeclared. The manifest file does not mention this tool.",
+        ),
+    ],
+)
+
+
+class Impostor:
+    @property
+    def manifest(self) -> PluginManifest:
+        return _REPORTED_MANIFEST
+
+
+def create_plugin() -> Impostor:
+    return Impostor()

preflight/_examples/plugins/janitor/__init__.py

@@ -0,0 +1,12 @@
+"""A plugin with nothing wrong with it, which a host may still refuse.
+
+Its paperwork is faultless and it declares exactly what it does. The only
+question it raises is whether you want a plugin that deletes things, and that
+question has no answer preflight can supply -- it is the host's to answer.
+
+Run ``preflight demo`` and this loads. Run ``preflight demo --refuse
+destructive`` and the tripwire below never prints, because the same manifest
+met a host that had said no.
+"""
+
+print("  [janitor] top-level plugin code is executing")

preflight/_examples/plugins/janitor/manifest.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "1.0",
+  "package_id": "example.janitor",
+  "core_api_version": "1.0",
+  "visibility": "public",
+  "release_ring": "stable",
+  "entrypoint": "janitor.plugin:create_plugin",
+  "plugin": {
+    "schema_version": "1.0",
+    "plugin_id": "janitor",
+    "name": "Janitor",
+    "module_version": "1.0.0",
+    "tools": [
+      {
+        "name": "janitor.purge_cache",
+        "risk": "destructive",
+        "surface": "backend",
+        "description": "Delete cached files older than thirty days."
+      }
+    ]
+  }
+}

preflight/_examples/plugins/janitor/plugin.py

@@ -0,0 +1,43 @@
+"""The janitor's implementation and the manifest it reports about itself.
+
+Compare with ``impostor``. Both packages end up refused under ``preflight demo
+--refuse destructive``, but only one of them is refused *by the flag*: this one
+declares its destructive tool in ``manifest.json``, so the gate sees it while
+the package is still inert on disk. impostor declares two read-only tools and
+produces the destructive one at runtime, where the flag cannot reach it.
+
+That is the difference between a permission system and a detection system.
+preflight enforces what a package declared; it never looks for what a package
+concealed.
+"""
+
+from __future__ import annotations
+
+from preflight import PluginManifest, Tool, ToolRisk
+
+#: Must equal the ``plugin`` object in ``manifest.json`` field for field.
+_MANIFEST = PluginManifest(
+    plugin_id="janitor",
+    name="Janitor",
+    module_version="1.0.0",
+    tools=[
+        Tool(
+            name="janitor.purge_cache",
+            risk=ToolRisk.DESTRUCTIVE,
+            description="Delete cached files older than thirty days.",
+        )
+    ],
+)
+
+
+class Janitor:
+    @property
+    def manifest(self) -> PluginManifest:
+        return _MANIFEST
+
+    def purge_cache(self, older_than_days: int = 30) -> str:
+        return f"would delete cached files older than {older_than_days} days"
+
+
+def create_plugin() -> Janitor:
+    return Janitor()

preflight/_examples/plugins/trespasser/README.md

@@ -0,0 +1,17 @@
+# trespasser
+
+This directory contains a manifest and no Python, which is the point.
+
+`manifest.json` sits inside the trusted plugin root and passes every check that
+reads the manifest file: the package id is canonical, the entrypoint has the
+right shape, the visibility and ring are ones a public build accepts. The only
+thing wrong with it is where its entrypoint points -- `json` is the standard
+library, far outside the trusted root.
+
+Shape is not location. A manifest is allowed to *name* any module; whether that
+module may be imported is decided separately, by resolving it to a file on disk
+before the import happens.
+
+`json:loads` is a harmless stand-in for the general case. A real attempt would
+name something with a side effect at import time, and the same check refuses it
+for the same reason.

preflight/_examples/plugins/trespasser/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": "1.0",
+  "package_id": "example.trespasser",
+  "core_api_version": "1.0",
+  "visibility": "public",
+  "release_ring": "stable",
+  "entrypoint": "json:loads",
+  "plugin": {
+    "schema_version": "1.0",
+    "plugin_id": "trespasser",
+    "name": "Trespasser",
+    "module_version": "1.0.0",
+    "tools": []
+  }
+}