Permission engine

How permissions work

A permission grants an agent the right to perform one or more actions on a resource. KavachOS evaluates permissions at call time by checking whether any of the agent's permissions match the requested resource and include the requested action, then verifying all constraints pass.

Matching rules

Resource pattern matching

Resources follow a colon-separated hierarchy. The resource field in a permission is matched against the resource in the authorization request using exact matches or wildcards.

mcp:github:repos        // exact match
mcp:github:*            // matches any direct child of mcp:github
mcp:*                   // matches anything directly under mcp
*                       // matches all resources

A wildcard matches exactly one segment. mcp:github:* matches mcp:github:repos and mcp:github:issues, but not mcp:github:repos:comments — that is two segments deeper.

// This permission...
{ resource: 'mcp:github:*', actions: ['read'] }

// ...matches these:
// mcp:github:repos          ✓
// mcp:github:issues         ✓
// mcp:github:pull_requests  ✓

// ...but NOT these:
// mcp:github                ✗  (no wildcard segment)
// mcp:slack:channels        ✗  (different namespace)
// mcp:github:repos:comments ✗  (two levels deeper)

Actions

Actions describe what the agent can do to a resource. KavachOS does not enforce a fixed set — you define what makes sense for your tools.

Common actions in MCP contexts:

An authorization check passes when an agent has a permission with: a matching resource pattern, the requested action in that permission's actions array, and all constraints satisfied.

Constraints

Constraints add conditions to a permission. All conditions must be met for the permission to apply.

Permission templates

KavachOS ships named templates for common patterns. Import them from kavachos:

import { permissionTemplates, getPermissionTemplate } from 'kavachos';

const agent = await kavach.agent.create({
  ownerId: 'user-123',
  name: 'readonly-agent',
  type: 'autonomous',
  permissions: permissionTemplates.readonly,
});

Available templates:

Templates are plain Permission[] arrays. Spread and extend them directly:

permissions: [
  ...permissionTemplates.mcpBasic,
  { resource: 'tool:custom_tool', actions: ['execute'] },
]

Use getPermissionTemplate(name) when you need a deep copy rather than a reference to the shared array:

const perms = getPermissionTemplate('mcpBasic');
perms[0].actions.push('write'); // safe — does not mutate the original

Next steps