Jean-Pierre

Appearance

View Markdown
References016042072075
Referenced by072081

RFD 077: Plugin Configuration and Trust Policy ​

Summary ​

This RFD defines the configuration surface for JP's plugin system. It introduces a [plugins] section in AppConfig that controls plugin installation, execution policy, binary checksum pinning, and per-plugin options. The config system replaces standalone approval files as the single source of truth for plugin trust decisions, and it participates in JP's existing config inheritance chain (global → workspace → local → CLI overrides).

Motivation ​

RFD 072 defines the command plugin system: standalone binaries that communicate with JP over a JSON-lines protocol. Phase 3 of that RFD adds a plugin registry and auto-install flow. But RFD 072 leaves open how users control plugin behavior:

  • Trust decisions are ad-hoc. Without config integration, plugin approval must be tracked in a separate JSON file that doesn't benefit from config inheritance. A user who trusts a plugin globally has no way to deny it in a specific workspace, or vice versa.

  • No checksum pinning. The registry provides checksums for download verification, but there is no mechanism for a user to pin a specific binary and refuse to run a changed one. This matters for supply-chain security: if a registry-hosted binary is compromised and re-published with a new checksum, users who haven't pinned are silently exposed.

  • No per-plugin options. Plugins like jp-serve need configuration (bind address, port) that is specific to the plugin. Without a config path, these settings must be passed as CLI arguments every time, or the plugin must invent its own config file.

  • Plugin types aren't distinguished. The registry currently assumes all plugins are command plugins. When wasm plugins (RFD 016) arrive, the registry and config need a way to distinguish between plugin kinds.

This RFD addresses all four gaps by defining the plugin config model and its interaction with the dispatch pipeline.

Design ​

Plugin Kind Taxonomy ​

The registry introduces a kind field on each plugin entry:

json
{
  "version": 1,
  "plugins": {
    "serve": {
      "kind": "command",
      "description": "Read-only web UI for conversations",
      "official": true,
      "binaries": { ... }
    }
  }
}

kind defaults to "command" when absent, so existing registry entries remain valid. The dispatch pipeline filters on kind and ignores entries with unrecognized values, allowing future plugin types (e.g. wasm) to be added to the registry without breaking older JP versions.

The PluginKind enum in jp_plugin::registry:

rust
pub enum PluginKind {
    Command,  // standalone binary, RFD 072 protocol
    // Wasm,  // future: RFD 016
}

Configuration Schema ​

The [plugins] section is added to AppConfig:

toml
[plugins]
# Auto-install official registry plugins on first invocation.
auto_install = true               # default: true

# Grace period (seconds) before SIGKILL after sending Shutdown.
shutdown_timeout_secs = 5         # default: 5

# Per-plugin configuration, keyed by plugin name.
[plugins.command.serve]
install = true                    # override auto_install per plugin
run = "unattended"                # execution policy

plugins.auto_install ​

Controls whether official plugins are automatically downloaded and installed when first invoked. When false, the user must run jp plugin install <name> explicitly. Third-party (non-official) plugins are never auto-installed regardless of this setting unless their per-plugin install field is true.

plugins.shutdown_timeout_secs ​

The grace period between sending Shutdown over the protocol and sending SIGKILL to the child process. Applies to all command plugins.

Per-Plugin Configuration ​

Each entry under plugins.command.<name> configures a specific command plugin:

toml
[plugins.command.serve]
install = true
run = "unattended"

[plugins.command.serve.checksum]
algorithm = "sha256"
value = "e3b0c44298fc1c149afbf4c8996fb924..."

[plugins.command.serve.options]
web.port = 3141
web.host = "127.0.0.1"

install (Option<bool>) — Whether to auto-install this plugin from the registry. Overrides the global auto_install for this specific plugin. When absent, falls back to the global setting (for official plugins) or false (for third-party plugins).

run (RunPolicy) — Execution policy:

ValueBehavior
askPrompt the user before running. Default for third-party
plugins and PATH-discovered plugins.
unattendedRun without prompting. Default for official registry
plugins.
denyNever run. JP exits with an error if the plugin is invoked.

The run policy applies at every execution point: installed plugins, registry auto-install, and PATH-discovered plugins. It replaces the standalone approval file system from the initial Phase 3 implementation.

checksum — Pins the binary to a specific hash. When set, JP computes the binary's checksum before execution and refuses to run if it doesn't match. This catches two scenarios:

  1. A registry-hosted binary is re-published with different content (supply-chain compromise).
  2. A PATH-discovered binary is replaced or modified.

The checksum config reuses the existing ChecksumConfig type from MCP server configuration:

rust
pub struct ChecksumConfig {
    pub algorithm: AlgorithmConfig,  // sha256 (default) | sha1
    pub value: String,               // hex-encoded digest
}

When a checksum mismatch occurs, JP prints the expected and actual values and tells the user which config key to update. This makes it easy to intentionally accept a new binary after reviewing the change.

options (Option<serde_json::Value>) — An opaque JSON value passed to the plugin in the config field of the init message. JP does not validate the contents — the plugin is responsible for parsing and error reporting. This follows the same pattern as tool options (RFD 042).

Example: the serve plugin reads options.web.port and options.web.host from its init config to configure its HTTP listener.

Config Inheritance ​

Plugin config participates in JP's standard config inheritance chain:

  1. Global config ($XDG_CONFIG_HOME/jp/config.toml): user-wide defaults. Trust a plugin globally, set default options.
  2. Workspace config (.jp/config.toml): per-project overrides. Deny a plugin in a sensitive workspace, or change its options.
  3. Local config (.jp.toml): directory-scoped overrides.
  4. CLI flags (--cfg plugins.command.serve.run=deny): one-shot overrides.

This means a user can set run = "unattended" globally and override it to run = "deny" in a workspace that handles sensitive data.

Plugin Management Without a Workspace ​

Plugin management commands (jp plugin list, jp plugin install, jp plugin update) run before workspace loading. They work from any directory, including outside of any JP workspace. This is intentional: plugin binaries are user-global (installed to $XDG_DATA_HOME/jp/plugins/), not workspace-local, so requiring jp init before installing a plugin would be unnecessary friction.

The trade-off is that management commands only see the user-global config layer. Workspace and local config layers are unavailable. This means a run = "deny" set in a workspace config is enforced during jp <plugin> dispatch (which runs inside a workspace) but not during jp plugin install (which runs outside). This is acceptable: deny means "don't run this plugin here," not "don't download it."

Dispatch Integration ​

The dispatch pipeline in resolve_plugin_binary reads AppConfig::plugins to make decisions at each resolution step:

  1. Deny check: If plugins.command.<name>.run = "deny", abort immediately.
  2. Installed plugins: Verify pinned checksum if configured.
  3. Registry install: Respect install and run policy. Official plugins with auto_install = true and run = "unattended" install silently. Third-party plugins with run = "ask" prompt interactively.
  4. PATH plugins: Verify pinned checksum. Respect run policy. Default is ask, which prompts once per invocation (not persisted — use run = "unattended" in config for permanent trust).
  5. Post-install verification: After downloading from the registry, verify against the pinned checksum if one is configured. This catches the scenario where the registry checksum passes (download is intact) but differs from the user's pinned value (binary changed since the user last reviewed it).

Future: Plugin Options Schema ​

The current options field is an opaque Value — JP passes it through without validation. A future extension could have plugins declare their options schema via the describe protocol:

json
{
  "type": "describe",
  "name": "serve",
  "options_schema": {
    "type": "object",
    "properties": {
      "web": {
        "type": "object",
        "properties": {
          "port": { "type": "integer", "default": 3141 },
          "host": { "type": "string", "default": "127.0.0.1" }
        }
      }
    }
  }
}

This would enable config validation, jp config show integration, and help text generation. It is explicitly deferred — the opaque approach is sufficient for the initial plugin set and avoids coupling the config system to plugin internals.

Drawbacks ​

  • No version constraints. The config has no version field for constraining which plugin version to install. This requires the registry to carry version metadata and JP to implement a resolution algorithm. The checksum pin provides a weaker but simpler guarantee: "run exactly this binary, or nothing."

  • Opaque options are unvalidated. A typo in options.web.prrt is silently ignored. The plugin may or may not report the error. This is the same tradeoff as tool options (RFD 042) and is acceptable until the options schema protocol is implemented.

  • No checksum auto-population. Users must manually obtain the checksum value (e.g., from the registry or by running shasum) and paste it into config. A future jp plugin pin <name> command could automate this.

Alternatives ​

Standalone approval file ​

The initial Phase 3 implementation stored plugin approvals in a separate $XDG_DATA_HOME/jp/plugin-approvals.json file, tracking binary path and checksum per approved plugin.

Rejected because:

  • Does not participate in config inheritance. Can't deny a plugin per-workspace.
  • Separate persistence mechanism to maintain alongside the config system.
  • No support for execution policy beyond binary approve/deny.
  • Mixes concerns: trust decisions (should this run?) and identity assertions (is this the right binary?) should be expressible independently.

Environment variables for plugin options ​

Pass plugin options via environment variables instead of the config file (e.g., JP_PLUGIN_SERVE_PORT=3141).

Rejected because:

  • Doesn't compose with config inheritance.
  • Awkward for nested options (port is fine, but complex structures don't map well to env vars).
  • The plugin protocol already sends the full config in the init message, so the transport is free.

Typed plugin config sections ​

Define a typed struct per plugin in jp_config (e.g., ServePluginConfig with port: u16 and host: String).

Rejected for the same reasons as in RFD 042: it couples the config crate to plugin internals and doesn't scale to third-party plugins. The opaque Value approach is the right starting point, with the schema protocol as the future validation layer.

Non-Goals ​

  • Plugin version management. Semantic version constraints, update channels, and rollback are package-manager features that are out of scope. Checksum pinning covers the security use case.

  • Options schema validation. Validating plugin options against a plugin-declared schema is deferred to a future RFD extending the describe protocol.

  • Wasm plugin configuration. RFD 016 defines the wasm plugin system. When wasm plugins need configuration, the plugins.wasm.<name> namespace is reserved but its schema is undefined here.

Risks and Open Questions ​

  • Checksum rotation workflow. When a plugin is legitimately updated, users with a pinned checksum must manually update the value. If many users pin checksums, plugin authors need a way to communicate new checksums (release notes, a jp plugin pin --update command, etc.). The UX for this needs attention.

  • Options forwarding path. The init message sends the full AppConfig as JSON. Plugin-specific options currently live at plugins.command.<name>.options in this blob. Plugins must navigate this path to find their options. A cleaner approach might extract the plugin's options and send them in a dedicated options field in the init message. This is a protocol change that should be coordinated with RFD 072.

  • Config scope during management commands. As described in the "Plugin Management Without a Workspace" section, management commands only see user-global config. If a future use case requires workspace-aware management (e.g. workspace-scoped plugin lists), the management commands would need to optionally load the workspace when one is available.

Implementation Plan ​

Phase 1: Config types and dispatch integration ​

  • Add PluginsConfig, CommandPluginConfig, and RunPolicy to jp_config.
  • Wire plugins into AppConfig with full AssignKeyValue / PartialConfigDelta / ToPartial support.
  • Reuse ChecksumConfig from MCP for checksum pinning.
  • Update resolve_plugin_binary to read config for policy decisions.
  • Remove the standalone approval file system.
  • Can be merged independently.

Phase 2: Options forwarding ​

  • Extract plugins.command.<name>.options from the config and include it in the plugin's init message in a well-known location.
  • Document the options path for plugin authors.
  • Depends on Phase 1.

Phase 3: Plugin kind in registry ​

  • Add kind field to RegistryPlugin (defaulting to "command").
  • Filter on kind in the dispatch pipeline.
  • Update jp plugin list to show plugin kind.
  • Can be merged independently of Phase 1.

References ​