Skip to main content

Chapter 10: Security Through Capabilities

TL;DR​

  • Your pack is sandboxed and has zero permissions by default.
  • To use a protected feature (like network access or opening a UI tab), declare it in capabilities in aip.json.
  • Example: 
    "capabilities": ["net.access", "ui.tabs.open"]
  • The user will be prompted to grant these permissions the first time your pack attempts to use them.

Worka is built on a foundation of security and user trust. A core part of this is the capability system, which ensures that users are always in control and that packs can only do what they are explicitly allowed to do.

The Principle of Least Privilege​

Worka operates on a zero‑trust model. When a user installs your pack, it is placed in a secure sandbox with no privileges by default. It cannot access the internet, the user’s files, or privileged UI actions.

To gain access to these features, your pack must declare its intent by requesting specific capabilities in its manifest. This follows the principle of least privilege: a pack should only have the exact permissions it needs to do its job, and nothing more.

What is a Capability?​

A capability is a granular permission to perform a specific, sensitive action. By declaring capabilities in your aip.json file, you are telling both the Worka Host and the user what your pack intends to do.

How to Declare Capabilities​

You declare the permissions your pack needs in the capabilities array within your aip.json file. This is a simple array of strings.

{
  ...
  "capabilities": [
    "net.access",
    "ui.tabs.open",
    "fs.read.*
  ]
}

Example Capabilities​

Common examples include:

  • net.access: outbound network requests
  • ui.tabs.open: open a new UI tab
  • storage.read / storage.write: access to pack‑scoped storage
  • db.schema.<pack>: access to pack‑owned schema

The User Experience: Lazy Granting​

To avoid overwhelming users with permissions, Worka uses lazy granting:

Permissions are prompted the first time a pack attempts to use them. The user’s choice is remembered per pack.

This just-in-time permission model provides a better user experience while maintaining a high level of security and control.