Plugin Permissions

Every plugin must declare the permissions it needs in omnilux-plugin.json. OmniLux enforces these at runtime — a plugin cannot perform actions outside its declared permissions.

Permission reference

Network

Permission	Description
network:outbound	Make outbound HTTP/HTTPS requests (fetch, API calls)
network:listen	Open a listening socket (rarely needed — most plugins use registered routes instead)

Storage

Permission	Description
storage:read	Read files from the media library
storage:write	Write files to the media library
storage:downloads	Read and write to the downloads directory

Database

Permission	Description
database:read	Read from the plugin's database tables
database:read-write	Read and write to the plugin's database tables

INFO

Plugins can only access their own database tables. Cross-plugin database access is not permitted.

Settings

Permission	Description
settings:read	Read plugin settings
settings:read-write	Read and write plugin settings

UI

Permission	Description
ui:settings-tab	Register a settings panel in the Settings page
ui:page	Register a full page in the web UI
ui:dashboard-widget	Register a widget on the dashboard

Scheduler

Permission	Description
scheduler:register	Register background jobs that run on a schedule

Notifications

Permission	Description
notifications:send	Send notifications through the notification system

Least privilege

Declare only the permissions your plugin actually needs. Examples:

Plugin type	Typical permissions
Notification agent	network:outbound, notifications:send
Download client	network:outbound, storage:downloads, database:read-write, settings:read-write, scheduler:register, ui:settings-tab
Indexer	network:outbound, database:read-write, settings:read-write
Metadata provider	network:outbound, settings:read
Scanner	storage:read, database:read-write, scheduler:register

Permission denied errors

If a plugin attempts an action without the required permission, a PermissionDeniedError is thrown:

PermissionDeniedError: Plugin "my-plugin" lacks permission "network:outbound"

The error is logged and the operation is blocked. The plugin continues running — only the denied operation fails.

Checking permissions in code

import { createPermissionChecker } from '@omnilux/plugin-sdk';

const checker = createPermissionChecker(manifest.permissions);

if (checker.has('network:outbound')) {
  // Safe to make HTTP requests
}