Skip to Content
OrbixDocs
Block SDK · Concepts

Permissions and capabilities

How trust tiers, manifest capability arrays, read tainting, and Marketplace install grants work together.

Every Orbix block runs under a trust tier and a capability set managed by capabilityEngine and orbixEgressFirewall.

Trust tiers

Orbix assigns every mounted block instance to one of three tiers:

  • trusted — First-party blocks shipped inside the Orbix application bundle (SHIPPED_BUILTIN_BLOCK_IDS or registered by host code via blockStudioRegistry.registerBuiltin()). Naming your block com.orbix.* does not grant trusted status; third-party com.orbix.* IDs are rejected at publish and install time.
  • community — The default tier for all user-authored, team, and Marketplace blocks once placed in a document.
  • external — Restricted tier for untrusted external embeds.

Default capabilities by tier

When a block omits a capability key from manifest.capabilities, it receives the default for its tier:

Capability keytrusted defaultcommunity defaultexternal default
document['read', 'write', 'navigate']['read']['read']
workspaceAll read:* + 'write:pages'['read:all_pages', 'read:graph', 'read:subpages', 'read:headings'][]
blocks['read', 'write', 'events', 'connections']['events'][]
database{ workspace: true }{ workspace: false, read: [], write: [] }{ workspace: false }
storage['local', 'persistent', 'cache', 'session']['local', 'cache']['cache']
ai['generate', 'context:document', 'context:selection', 'vision']['generate'][]
workers['compute', 'wasm']['compute'][]
clipboard['read', 'write']['write'][]
network{ domains: ['*'], methods: ['GET','POST','PUT','DELETE','PATCH','HEAD'] }{ domains: [], methods: ['GET', 'POST'] }{ domains: [], methods: ['GET'] }

How declared capabilities merge with defaults

For community and external blocks, capabilityEngine.getCapabilities(blockId) merges your manifest over the tier defaults one top-level key at a time:

const effective = { ...tierDefaults, ...declaredCapabilities };

Declaring a key replaces its default array

Because each declared key replaces that key's default array, always include the default entries you still need.

For example, community blocks receive storage: ['local', 'cache'] by default. If you write:

"capabilities": {
  "storage": ["persistent"]
}

then 'local' is no longer in storage, so useStorage and local useLiveQuery calls will fail. Write "storage": ["local", "persistent"] instead.

Canonical capability syntax

Declare capabilities as arrays of strings (plus objects for network and database):

manifest.json
{
  "capabilities": {
    "document": ["read", "write"],
    "workspace": ["read:all_pages", "write:pages"],
    "blocks": ["events", "connections"],
    "storage": ["local", "persistent"],
    "ai": ["generate", "context:selection"],
    "workers": ["compute"],
    "clipboard": ["read", "write"],
    "database": {
      "read": ["tasks_db"],
      "write": ["tasks_db"]
    },
    "network": {
      "domains": ["api.example.com"],
      "methods": ["GET", "POST"]
    }
  }
}

For backward compatibility with older manifests, capabilityEngine.registerManifest also normalizes legacy boolean-flag objects (such as { "storage": { "local": true } } or { "network": { "allowedDomains": ["api.example.com"] } }) into the canonical form above at registration time. Always prefer the array + network.domains format in new blocks.

Studio Preview vs placed document blocks

  • Block Studio Preview: Binds the preview instance with preview: true (authorPreview), granting full trusted-equivalent access so you can experiment freely while editing code.
  • Document instances: Bind with preview: false at the community tier. Missing capabilities throw SecurityCapabilityError synchronously on hook calls (or reject the returned Promise on async storage/AI/fetch calls).

Read tainting (data air-gap)

To prevent a community block from reading private workspace pages and sending their contents to an external server:

  1. Calling verifyDocument('read'), verifyWorkspace(...), verifyDatabase('read', ...), or verifyBlocks('read') on a non-trusted block calls orbixEgressFirewall.markBlockTaintedByRead(blockId, scope).
  2. Once a block instance is tainted, orbixEgressFirewall blocks all subsequent outbound fetch / XMLHttpRequest / sendBeacon / WebSocket requests to external servers from that instance (authorized useOrbixAI calls remain permitted when ai capabilities are declared).
  3. At Marketplace install time, BlockPermissionStore.grantPermissions also strips network permission whenever workspace or cross_block_data permissions are granted.

Marketplace install review

Orbix does not display runtime "Allow / Deny" modal prompts when a user clicks inside a block. Instead, when installing a block from the Marketplace, BlockPermissionSheet displays the permissions and outbound domains detected by BlockCodeAnalyzer so the user can review and toggle grants upfront before the block runs.

On this page