Permissions Reference

StudioBrain plugins declare the capabilities they need in plugin.json. The host runtime enforces these declarations, granting access only to what the plugin has declared and the user has approved. This page is the complete reference for the capability system.

Capability Matrix

Auto-granted capabilities

These capabilities are enabled automatically when a plugin is installed. They are considered safe because they are read-only or usage-tracked:

• entity_read — The plugin can read entity frontmatter and markdown content. It cannot modify anything.
• asset_read — The plugin can read files attached to entities (images, documents, audio). Read-only.
• ai_generate — The plugin can call the AI generation service. Usage is metered through your BrainBits balance, so the plugin cannot generate unbounded costs.

Consent-required capabilities

These capabilities require the user to approve a consent dialog before the plugin can use them:

• entity_write — The plugin can create new entities, modify existing entity fields and content, and delete entities. All changes appear in version history.
• asset_write — The plugin can upload new assets, replace existing assets, and delete assets from entities.
• http_request — The plugin can make outbound HTTP requests. See Domain Restrictions for Cloud-specific behavior.

Platform-restricted capabilities

These capabilities are blocked on certain platforms regardless of user consent:

• file_read — Read files from the local filesystem. Available on Desktop and Core with consent. Blocked on Cloud because Cloud runs in a server environment where filesystem access is not meaningful for plugins.
• file_write — Write files to the local filesystem. Same restrictions as file_read.

Domain Restrictions

The http_request capability works differently across platforms:

Cloud (Strict enforcement)

On Cloud, plugins can only make HTTP requests to domains declared in capabilities.http_domains in their plugin.json. Requests to any other domain are blocked by the host runtime.

{
  "capabilities": {
    "host_functions": ["http_request"],
    "http_domains": [
      "api.example.com",
      "*.example.org"
    ]
  }
}

Wildcard patterns:

• *.example.com matches api.example.com, cdn.example.com, but not example.com itself.
• example.com matches only example.com (no subdomains).
• * is not allowed (cannot declare access to all domains on Cloud).

Desktop and Core (Informational)

On Desktop and Core, the declared domains are shown in the consent dialog for transparency, but they are not enforced. After the user approves the http_request capability, the plugin can reach any domain.

Capability Details

entity_read

What it grants: Read access to entity data through host functions.

Host functions enabled:

• entity_read(entity_type, entity_id) — Read a single entity
• entity_list(query) — List entities with filters

What the plugin sees:

• Entity frontmatter (all YAML fields)
• Entity markdown body
• Entity metadata (created_at, updated_at, entity_type, entity_id)

What the plugin cannot do:

• Modify any entity data
• Access entities outside the current project scope (on StudioBrain Cloud, multi-tenant isolation is enforced by the host)

asset_read

What it grants: Read access to entity assets.

Host functions enabled:

• asset_read(entity_type, entity_id, filename) — Read a single asset file

What the plugin sees:

• Binary content of the asset file
• Asset filename and content type

What the plugin cannot do:

• Modify or delete assets
• Access assets from entities it cannot read (respects entity_read scope)

ai_generate

What it grants: Access to the StudioBrain AI generation service.

Host functions enabled:

• ai_generate(prompt, model, options) — Generate text content

Billing:

• Each generation call consumes BrainBits from the user’s account
• The plugin cannot exceed the user’s available balance
• Usage is attributed to the plugin in the billing dashboard

Rate limits:

• Same rate limits as the user’s direct AI usage
• Shared quota (plugin calls count toward the user’s limits)

entity_write

What it grants: Write access to entities.

Host functions enabled:

• entity_create(entity_type, data) — Create a new entity
• entity_update(entity_type, entity_id, content) — Update an existing entity
• entity_delete(entity_type, entity_id) — Delete an entity

Audit trail:

• All write operations are logged in the entity’s version history
• The log entry shows the plugin ID as the author (e.g., “Modified by plugin: jira-sync”)

Scope:

• Write access applies to all entity types the plugin has access to
• On StudioBrain Cloud, tenant isolation is enforced (a plugin cannot write to another tenant’s entities)

asset_write

What it grants: Write access to entity assets.

Host functions enabled:

• asset_write(entity_type, entity_id, filename, data) — Upload or replace an asset

Constraints:

• Same size limits as manual uploads (configurable per edition)
• Asset type restrictions apply (configured in entity templates)

http_request

What it grants: Ability to make outbound HTTP requests from the WASM sandbox.

Host functions enabled:

• http_request(url, method, headers, body) — Make an HTTP request

Domain enforcement (Cloud):

• Only domains in http_domains are reachable
• The host validates the URL before making the request
• Blocked requests return an error with domain_not_allowed

No enforcement (Desktop/Core):

• All domains are reachable after consent
• Declared domains are shown in the consent dialog for transparency

Request limits:

• 30 requests per minute per plugin instance
• 5 second timeout per request
• 1 MB maximum response body

file_read

What it grants: Read access to the local filesystem.

Host functions enabled:

• file_read(path) — Read a file from the local filesystem

Platform availability:

file_write

What it grants: Write access to the local filesystem.

Host functions enabled:

• file_write(path, data) — Write a file to the local filesystem

Platform availability: Same as file_read.

Safety:

• WASM plugins can only write to declared paths
• Native Python/Lua plugins have unrestricted write access
• No automatic backups are made before writes — plugins are responsible for safe writes

Consent Dialog Behavior

When a plugin is installed (or updated with new capabilities), StudioBrain shows a consent dialog for any non-auto-granted capabilities.

What the dialog shows

Plugin "My Plugin" requests the following permissions:

  [auto]  entity_read     Read your entity data
  [auto]  asset_read      Read your entity assets
  [!]     entity_write    Create and modify your entities
  [!]     http_request    Make network requests to:
                          api.example.com, cdn.example.org

  [Enable]  [Cancel]

• [auto] items are informational. They are granted regardless of the user’s choice.
• [!] items require explicit approval. If the user clicks Cancel, the plugin is not installed.
• For http_request, the declared domains are listed.

Partial approval

The current consent model is all-or-nothing for consent-required capabilities. If a plugin requests entity_write and http_request, you must approve both or cancel the installation entirely.

After installation, you can revoke individual capabilities in Settings > Plugins > [Plugin] > Permissions. The plugin may not function correctly without all its declared capabilities.

Re-consent on update

If a plugin update adds new consent-required capabilities, the consent dialog appears again showing only the new capabilities. Previously approved capabilities are not shown again.

Storage and Config Capabilities

The following host functions are always available to any plugin, regardless of declared capabilities:

These functions operate within the plugin’s own scope. A plugin cannot read another plugin’s storage or settings.

Security Considerations

WASM sandbox guarantees

• Plugins cannot access host memory outside their linear memory.
• Plugins cannot call host functions they have not declared.
• Plugins cannot bypass domain restrictions on Cloud.
• Plugins cannot access other plugins’ data or storage.

What the sandbox does NOT protect against

• A plugin with entity_write can modify any entity the user has access to.
• A plugin with http_request can exfiltrate entity data to declared domains.
• A plugin with ai_generate can consume BrainBits.
• Native (Python/Lua) plugins bypass all sandbox restrictions.

Recommendations

• Install only plugins from authors you trust.
• Review the declared capabilities before approving the consent dialog.
• Prefer WASM plugins over native Python/Lua plugins.
• Revoke capabilities you do not need after installation.
• Monitor plugin activity in Settings > Plugins > [Plugin] > Activity Log.

Next Steps

• Plugin System Overview — How the plugin system works
• Using the Marketplace — Browse, install, and manage plugins
• Creating Plugins — Build your own plugin
• Host Functions API — Detailed function documentation