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), you must declare it in the capabilities array 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 even basic UI functions like opening a tab.

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.*
  ]
}

Common Capabilities​

Here are some of the most common capabilities you might need:

  • net.access: Allows your pack's backend to make outbound network requests to the internet.
  • ui.tabs.open: Allows your pack's UI to ask the Host to open a new tab.
  • fs.read.*: Allows your pack to read files from the user's local filesystem. You can use glob patterns to restrict access to certain paths or file types (e.g., fs.read.~/Documents/*.pdf).
  • fs.write.*: Allows your pack to write files to the user's local filesystem.
  • db.query.*: Allows your pack to query the host database via the worka/db virtual pack.
  • require_host_execution: This is a high-privilege capability. It allows your pack's backend to run directly on the host operating system instead of inside a container. This should only be used when absolutely necessary (e.g., for a pack that needs to interact with specific hardware) and will trigger a stronger warning to the user.

The User Experience: Lazy Granting​

To avoid overwhelming users with a long list of permissions during installation, Worka uses a "lazy granting" model.

The user is not asked to approve permissions when they install your pack. Instead, the Worka Host waits and intercepts the first time your pack attempts to use a specific capability. At that moment, a prompt appears asking the user to allow or deny that specific permission. Once the user makes a choice, Worka remembers it for that pack, so they won't be asked again.

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