Permissions & Security
Plugins request only the capabilities their feature needs. Users review the publisher, requested permissions and compatibility before enabling a plugin; new permissions require a new grant. A community bundle's version, artifact or descriptor digest change also invalidates its previous grants. Disablement or revocation is effective at the host boundary and removes the corresponding contribution.
Plugin API v1 permissions
| Permission | Host capability |
|---|---|
library.read | Safe library summaries, never file paths. |
library.metadata.read | Safe metadata needed for enrichment. |
metadata.propose | Field-level, user-reviewable metadata proposals. |
playback.read | Current playback state without playback control. |
network.connect, network.fetch | Restricted, host-mediated network access. |
storage.private | Small namespaced plugin state subject to a quota. |
jobs.schedule | Host-owned bounded background jobs. |
ui.contribute | Declarative UI contributions. |
diagnostics.write | Bounded structured diagnostics. |
network.iroh:music-hub-network and
storage.addon:music-hub-network are reserved for the bundled Music Hub
Network core add-on. They are not in the community-bundle allowlist.
The host denies a call when the plugin is disabled, the permission is not granted, input fails validation, or a quota, rate limit or timeout is exceeded. Plugin code never receives raw database handles, local file paths, Node/Electron globals, shell access, app configuration, service credentials, pairing secrets or mobile bearer tokens.
Plugins must never auto-apply remote metadata. Return proposals with source and evidence; the host requires an explicit per-field decision, records provenance, and can provide undo where the underlying host operation supports it.