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_IDSor registered by host code viablockStudioRegistry.registerBuiltin()). Naming your blockcom.orbix.*does not granttrustedstatus; third-partycom.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 key | trusted default | community default | external default |
|---|---|---|---|
document | ['read', 'write', 'navigate'] | ['read'] | ['read'] |
workspace | All 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):
{
"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 fulltrusted-equivalent access so you can experiment freely while editing code. - Document instances: Bind with
preview: falseat thecommunitytier. Missing capabilities throwSecurityCapabilityErrorsynchronously 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:
- Calling
verifyDocument('read'),verifyWorkspace(...),verifyDatabase('read', ...), orverifyBlocks('read')on a non-trusted block callsorbixEgressFirewall.markBlockTaintedByRead(blockId, scope). - Once a block instance is tainted,
orbixEgressFirewallblocks all subsequent outboundfetch/XMLHttpRequest/sendBeacon/WebSocketrequests to external servers from that instance (authorizeduseOrbixAIcalls remain permitted whenaicapabilities are declared). - At Marketplace install time,
BlockPermissionStore.grantPermissionsalso stripsnetworkpermission wheneverworkspaceorcross_block_datapermissions 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.