Skip to main content

​
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.
​
resource
string
Colon-separated resource path. Wildcards (*) match exactly one segment.
​
actions
string[]
The actions this permission grants. No fixed set, define what fits your tools.
​
constraints
PermissionConstraints
default:"undefined"
Optional conditions that must all be satisfied for the permission to apply.

​
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:
ActionTypical use
readFetching data, listing resources
writeCreating or modifying resources
executeRunning tools, shell commands, deployments
deletePermanent removal of resources
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.
​
maxCallsPerHour
number
default:"undefined (no limit)"
Sliding 5-minute window rate limit. Calls beyond this return RATE_LIMIT_EXCEEDED.
​
allowedArgPatterns
string[]
default:"undefined (any arguments allowed)"
Glob-style patterns. The arguments field in the authorization request must match at least one.
​
requireApproval
boolean
default:"false"
When true, the call is denied with APPROVAL_REQUIRED. Your app must handle the approval flow.
​
timeWindow
{ start: string; end: string }
default:"undefined (any time)"
HH:MM format, UTC. Calls outside this range are denied.
​
ipAllowlist
string[]
default:"undefined (any IP)"
CIDR ranges. Requests from IPs outside this list are denied.
Limits how many times an agent can call a resource per hour. Uses a 5-minute sliding window.
{
  resource: 'mcp:deploy:staging',
  actions: ['execute'],
  constraints: {
    maxCallsPerHour: 20,
  },
}
Calls beyond the limit return result: 'rate_limited' in the audit log and allowed: false with reason RATE_LIMIT_EXCEEDED.
Restricts what arguments an agent can pass to a tool. Patterns are glob-style strings matched against the arguments field of the authorization request.
{
  resource: 'tool:file_write',
  actions: ['execute'],
  constraints: {
    allowedArgPatterns: ['/home/agent/**', '/tmp/**'],
  },
}
If no pattern matches, the call is denied.
Prevents automatic authorization. The call is logged and denied until a human approves it through your application’s approval flow.
{
  resource: 'mcp:deploy:production',
  actions: ['execute'],
  constraints: {
    requireApproval: true,
  },
}
The authorization result has allowed: false and reason APPROVAL_REQUIRED. Your application is responsible for presenting the approval UI and re-authorizing after approval.
KavachOS does not ship an approval UI. It provides the enforcement point. How you build the human review step is up to you.
Restricts when an action is allowed. Times are in 24-hour format, UTC.
{
  resource: 'mcp:github:*',
  actions: ['read', 'write'],
  constraints: {
    timeWindow: { start: '09:00', end: '17:00' },
  },
}
Calls outside the window return allowed: false. Useful for business-hours-only policies or maintenance windows.
Restricts which source IPs can use the permission. Accepts CIDR notation.
{
  resource: 'mcp:internal:*',
  actions: ['read', 'write', 'execute'],
  constraints: {
    ipAllowlist: ['10.0.0.0/8', '172.16.0.0/12'],
  },
}
Pass the caller’s IP in the authorization request for this to take effect. Requests from IPs outside the list are denied.

​
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:
TemplateActionsResourceNotes
readonlyread*
readwriteread, write*
admin**All actions on all resources
mcpBasicread, executemcp:*
mcpFullread, write, executemcp:*
rateLimitedReadread*100 calls/hour
approvalRequired**Every call requires human approval
businessHoursread, write, execute*09:00–17:00 UTC
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
Spreading directly from permissionTemplates gives you a reference to the original array entries. If you mutate the objects after spreading, you will modify the template. Use getPermissionTemplate when you need to modify entries.

​
Next steps

Delegation chains

Delegate permission subsets to other agents.

Audit trail

See how permissions are logged on every call.

Compliance

Map permissions to EU AI Act and NIST requirements.