wolfhece._plugin_trust

Plugin trust store — persists per-plugin approval decisions.

Trust levels

BUILTIN

The plugin ships inside wolfhece/_builtin_plugins/. Always trusted, no user action required.

APPROVED

The user has explicitly approved the plugin in its current state: the SHA-256 digest of companion.py + plugin.toml matches the stored value.

CHANGED

The user previously approved the plugin, but at least one of the two tracked files has changed since then. Re-approval is required.

UNKNOWN

The plugin has never been seen; the user has not yet been asked.

Usage example

from wolfhece._plugin_trust import get_default_store, TrustStatus

store = get_default_store()
status = store.get_status(plugin_info)
if status in (TrustStatus.UNKNOWN, TrustStatus.CHANGED):
    # --- show approval dialog to the user ---
    store.approve(plugin_info)

The trust file is a human-readable JSON document stored in the OS user-config directory (no extra dependencies required):

• Windows — %APPDATA%\wolfhece\trusted_plugins.json

• Linux / macOS — $XDG_CONFIG_HOME/wolfhece/trusted_plugins.json (defaults to ~/.config/wolfhece/)

Module Contents

wolfhece._plugin_trust._logger

wolfhece._plugin_trust.BUILTIN_PLUGINS_DIR: pathlib.Path

class wolfhece._plugin_trust.TrustStatus(*args, **kwds)

Bases: enum.Enum

Approval status of a discovered plugin.

BUILTIN

APPROVED

CHANGED

UNKNOWN

wolfhece._plugin_trust.compute_plugin_hash(plugin_dir: pathlib.Path) → str

Return a SHA-256 hex digest that covers companion.py + plugin.toml.

Both file names are included in the digest so that renaming a file without changing its content still invalidates the hash. The files are processed in a deterministic order so the result is stable across platforms.

Parameters:

plugin_dir – Root directory of the plugin (must contain both files).

Returns:

64-character lowercase hex string.

wolfhece._plugin_trust._user_config_dir() → pathlib.Path

Return the wolfhece user-config directory without importing extras.

class wolfhece._plugin_trust.TrustStore(trust_file: pathlib.Path | None = None)

Persist per-plugin approval decisions in a local JSON file.

Each entry maps a plugin slug (PluginInfo.name) to a record with:

• hash — SHA-256 digest at the time of approval

• approved_at — ISO-8601 UTC timestamp

• display_name — for human readability only

• version — version string at the time of approval

Parameters:

trust_file – Path to the JSON trust file. Defaults to <user-config-dir>/wolfhece/trusted_plugins.json.

_trust_file: pathlib.Path = None

_data: dict[str, dict]

_load() → dict[str, dict]

_save() → None

get_status(info: wolfhece._plugin_loader.PluginInfo) → TrustStatus

Return the TrustStatus for info.

The check is performed in this order:

1. If the plugin path is inside BUILTIN_PLUGINS_DIR → BUILTIN.

2. If no record exists for info.name → UNKNOWN.

3. If the stored hash matches the current digest → APPROVED.

4. Otherwise → CHANGED.

approve(info: wolfhece._plugin_loader.PluginInfo) → None

Record user approval for the current state of info.

Computes the hash of companion.py + plugin.toml and stores it alongside a timestamp and human-readable metadata.

revoke(name: str) → None

Remove any stored approval for the plugin name.

After revocation get_status() returns UNKNOWN for that slug.

get_approved_at(name: str) → str | None

Return the ISO-8601 timestamp of the last approval, or None.

property trust_file: pathlib.Path

Path to the backing JSON file.

wolfhece._plugin_trust._default_store: TrustStore | None = None

wolfhece._plugin_trust.get_default_store() → TrustStore

Return the process-wide TrustStore (created on first call).

wolfhece._plugin_trust.reset_default_store(trust_file: pathlib.Path | None = None) → TrustStore

Replace the default store — useful for testing.

Parameters:

trust_file – Custom path; None resets to the system default.

Returns:

The new TrustStore instance.