Personal AI, On Personal Devices
Python
"""RBAC capability system — fine-grained permission model for tool dispatch."""
from __future__ import annotations
import fnmatch
import json
import logging
from dataclasses import dataclass, field
from enum import Enum
from pathlib import Path
from typing import Any, Dict, List, Optional
logger = logging.getLogger(__name__)
class Capability(str, Enum):
"""Fine-grained capability labels."""
FILE_READ = "file:read"
FILE_WRITE = "file:write"
NETWORK_FETCH = "network:fetch"
CODE_EXECUTE = "code:execute"
MEMORY_READ = "memory:read"
MEMORY_WRITE = "memory:write"
CHANNEL_SEND = "channel:send"
TOOL_INVOKE = "tool:invoke"
SCHEDULE_CREATE = "schedule:create"
SYSTEM_ADMIN = "system:admin"
@dataclass(slots=True)
class CapabilityGrant:
"""A single capability grant for an agent."""
capability: str # Capability value or glob pattern
pattern: str = "*" # resource glob pattern
@dataclass(slots=True)
class AgentPolicy:
"""Policy for a specific agent."""
agent_id: str
grants: List[CapabilityGrant] = field(default_factory=list)
deny: List[str] = field(default_factory=list) # explicit denials
class CapabilityPolicy:
"""RBAC capability policy for tool dispatch.
Checks whether an agent has the required capability to invoke a tool.
Policy can be loaded from a JSON file or configured programmatically.
Default policy: if no explicit policy exists for an agent, all
capabilities are granted (open by default). Set ``default_deny=True``
to flip to deny-by-default.
"""
def __init__(
self,
*,
policy_path: Optional[str] = None,
default_deny: bool = False,
) -> None:
self._policies: Dict[str, AgentPolicy] = {}
self._default_deny = default_deny
from openjarvis._rust_bridge import get_rust_module
_rust = get_rust_module()
self._rust_impl = _rust.CapabilityPolicy(default_deny=default_deny)
if policy_path:
self._load_file(Path(policy_path))
def grant(self, agent_id: str, capability: str, pattern: str = "*") -> None:
"""Grant a capability to an agent."""
policy = self._policies.setdefault(
agent_id,
AgentPolicy(agent_id=agent_id),
)
policy.grants.append(CapabilityGrant(capability=capability, pattern=pattern))
self._rust_impl.grant(agent_id, capability, pattern)
def deny(self, agent_id: str, capability: str) -> None:
"""Explicitly deny a capability to an agent."""
policy = self._policies.setdefault(
agent_id,
AgentPolicy(agent_id=agent_id),
)
policy.deny.append(capability)
self._rust_impl.deny(agent_id, capability)
_DEFAULT_AGENT = "_default"
def check(self, agent_id: str, capability: str, resource: str = "") -> bool:
"""Check whether *agent_id* has *capability* for *resource*.
Falls back to the ``_default`` wildcard agent's grants only when
*agent_id* has no explicit policy of its own. This lets a baseline be
granted once via
``grant("_default", ...)`` instead of needing to know every
dynamically-created managed-agent UUID ahead of time while preserving
the invariant that an agent-specific denial always wins.
"""
if (
not agent_id
or agent_id == self._DEFAULT_AGENT
or agent_id in self._policies
):
return self._rust_impl.check(agent_id, capability, resource)
if self._DEFAULT_AGENT in self._policies:
return self._rust_impl.check(self._DEFAULT_AGENT, capability, resource)
return self._rust_impl.check(agent_id, capability, resource)
def _check_python(self, agent_id: str, capability: str, resource: str = "") -> bool:
"""Legacy Python check — kept for reference only."""
policy = self._policies.get(agent_id)
if policy is None:
# No explicit policy — use default
return not self._default_deny
# Explicit denials take precedence
for denied in policy.deny:
if fnmatch.fnmatch(capability, denied):
return False
# Check grants
for grant in policy.grants:
if fnmatch.fnmatch(capability, grant.capability):
if resource and grant.pattern != "*":
if fnmatch.fnmatch(resource, grant.pattern):
return True
else:
return True
# No matching grant found
return not self._default_deny
def list_grants(self, agent_id: str) -> List[CapabilityGrant]:
"""List all grants for an agent."""
policy = self._policies.get(agent_id)
return list(policy.grants) if policy else []
def list_agents(self) -> List[str]:
"""List all agents with explicit policies."""
return list(self._policies.keys())
def _load_file(self, path: Path) -> None:
"""Load an explicitly configured policy, rejecting incomplete policy data."""
# A missing/malformed file must not silently discard configured denies.
# Validate the complete document before applying any grants.
data = json.loads(path.read_text())
if not isinstance(data, dict) or not isinstance(data.get("agents"), list):
raise ValueError("Capability policy must contain an agents list")
for agent_data in data["agents"]:
if not isinstance(agent_data, dict):
raise ValueError("Capability policy agent must be an object")
agent_id = agent_data.get("agent_id")
if not isinstance(agent_id, str) or not agent_id.strip():
raise ValueError("Capability policy agent_id must be a nonempty string")
grants = agent_data.get("grants", [])
denied = agent_data.get("deny", [])
if not isinstance(grants, list) or not isinstance(denied, list):
raise ValueError("Capability policy grants and deny must be lists")
for grant in grants:
if (
not isinstance(grant, dict)
or not isinstance(grant.get("capability"), str)
or not grant["capability"].strip()
or not isinstance(grant.get("pattern", "*"), str)
):
raise ValueError(
"Capability policy grant must specify a capability"
)
if any(not isinstance(cap, str) or not cap.strip() for cap in denied):
raise ValueError("Capability policy deny entries must be strings")
for agent_data in data["agents"]:
agent_id = agent_data["agent_id"]
# An explicit empty policy is still an identity-specific policy;
# it must not accidentally inherit the wildcard's grants.
self._policies.setdefault(agent_id, AgentPolicy(agent_id=agent_id))
for grant in agent_data.get("grants", []):
self.grant(agent_id, grant["capability"], grant.get("pattern", "*"))
for denied in agent_data.get("deny", []):
self.deny(agent_id, denied)
def save(self, path: Path) -> None:
"""Save policy to a JSON file."""
agents = []
for agent_id, policy in self._policies.items():
agents.append(
{
"agent_id": agent_id,
"grants": [
{"capability": g.capability, "pattern": g.pattern}
for g in policy.grants
],
"deny": policy.deny,
}
)
path.write_text(json.dumps({"agents": agents}, indent=2))
# Canonical capability requirements for every in-tree tool. This table is a
# security floor: ToolSpec declarations may add requirements, but they may not
# weaken these. Keep explicitly-safe tools in the table with an empty list so
# an omitted future built-in can be distinguished from a reviewed safe one.
DEFAULT_TOOL_CAPABILITIES: Dict[str, List[str]] = {
"agent_kill": [Capability.SYSTEM_ADMIN],
"agent_list": [Capability.SYSTEM_ADMIN],
"agent_send": [Capability.SYSTEM_ADMIN],
"agent_spawn": [Capability.SYSTEM_ADMIN],
"apply_patch": [Capability.FILE_WRITE],
"audio_transcribe": [Capability.FILE_READ, Capability.NETWORK_FETCH],
"browser_axtree": [Capability.NETWORK_FETCH],
"browser_click": [Capability.NETWORK_FETCH],
"browser_extract": [Capability.NETWORK_FETCH],
"browser_navigate": [Capability.NETWORK_FETCH],
"browser_screenshot": [Capability.NETWORK_FETCH],
"browser_type": [Capability.NETWORK_FETCH],
"calculator": [],
"calendar_search": [Capability.FILE_READ],
"calendar_upcoming": [Capability.FILE_READ],
"cancel_scheduled_task": [Capability.SCHEDULE_CREATE],
"channel_list": [Capability.SYSTEM_ADMIN],
"channel_send": [Capability.CHANNEL_SEND],
"channel_status": [Capability.SYSTEM_ADMIN],
"check_permission": [Capability.MEMORY_READ],
"code_interpreter": [Capability.CODE_EXECUTE],
"code_interpreter_docker": [Capability.CODE_EXECUTE],
"db_query": [Capability.CODE_EXECUTE],
"digest_collect": [Capability.MEMORY_READ, Capability.NETWORK_FETCH],
"docker_shell_exec": [Capability.CODE_EXECUTE],
"execute_pending_actions": [
Capability.SYSTEM_ADMIN,
Capability.CHANNEL_SEND,
Capability.NETWORK_FETCH,
],
"file_read": [Capability.FILE_READ],
"file_write": [Capability.FILE_WRITE],
"get_pending_actions": [Capability.MEMORY_READ],
"fx_macro_data": [Capability.NETWORK_FETCH],
"get_weather": [Capability.NETWORK_FETCH],
"git_commit": [Capability.FILE_WRITE],
"git_diff": [Capability.FILE_READ],
"git_log": [Capability.FILE_READ],
"git_status": [Capability.FILE_READ],
"http_request": [Capability.NETWORK_FETCH],
"image_generate": [Capability.NETWORK_FETCH, Capability.FILE_WRITE],
"kg_add_entity": [Capability.MEMORY_WRITE],
"kg_add_relation": [Capability.MEMORY_WRITE],
"kg_neighbors": [Capability.MEMORY_READ],
"kg_query": [Capability.MEMORY_READ],
"knowledge_search": [Capability.MEMORY_READ],
"knowledge_sql": [Capability.MEMORY_READ],
"list_scheduled_tasks": [Capability.SCHEDULE_CREATE],
"llm": [Capability.NETWORK_FETCH],
"memory_index": [Capability.MEMORY_WRITE],
"memory_manage": [Capability.MEMORY_READ, Capability.MEMORY_WRITE],
"memory_retrieve": [Capability.MEMORY_READ],
"memory_search": [Capability.MEMORY_READ],
"memory_store": [Capability.MEMORY_WRITE],
"pause_scheduled_task": [Capability.SCHEDULE_CREATE],
"pdf_extract": [Capability.FILE_READ],
"queue_action": [Capability.MEMORY_WRITE],
"record_decision": [Capability.SYSTEM_ADMIN, Capability.MEMORY_WRITE],
"repl": [Capability.CODE_EXECUTE],
"resume_scheduled_task": [Capability.SCHEDULE_CREATE],
"retrieval": [Capability.MEMORY_READ],
"scan_chunks": [Capability.MEMORY_READ],
"schedule_task": [Capability.SCHEDULE_CREATE],
"shell_exec": [Capability.CODE_EXECUTE],
"skill_manage": [Capability.FILE_READ, Capability.FILE_WRITE],
"text_to_speech": [Capability.NETWORK_FETCH, Capability.FILE_WRITE],
"think": [],
"user_profile_manage": [Capability.FILE_READ, Capability.FILE_WRITE],
"web_search": [Capability.NETWORK_FETCH],
}
_SAFE_BUILTIN_PROVENANCE = {
"calculator": ("openjarvis.tools.calculator", "CalculatorTool"),
"think": ("openjarvis.tools.think", "ThinkTool"),
}
def canonical_tool_capabilities(tool: Any) -> List[str]:
"""Return the non-bypassable capability floor for *tool*.
Third-party tools remain governed by their ToolSpec. An in-tree tool that
was newly registered without being inventoried fails closed as
``system:admin`` instead of silently becoming unrestricted.
"""
module = type(tool).__module__
name = tool.spec.name
is_builtin = (
module == "openjarvis.tools"
or module.startswith("openjarvis.tools.")
or module == "openjarvis.scheduler.tools"
)
if module == "openjarvis.tools.mcp_adapter":
# MCP tool names are remote-controlled. Resolve adapter provenance
# before the name table so a server cannot impersonate a reviewed-safe
# local tool such as ``calculator`` or ``think``.
return [Capability.TOOL_INVOKE]
if is_builtin:
if name in DEFAULT_TOOL_CAPABILITIES:
canonical = list(DEFAULT_TOOL_CAPABILITIES[name])
expected = _SAFE_BUILTIN_PROVENANCE.get(name)
if (
expected is not None
and (
module,
type(tool).__name__,
)
!= expected
):
logger.error(
"Tool %r claimed reviewed-safe built-in provenance from %s.%s",
name,
module,
type(tool).__name__,
)
return [Capability.SYSTEM_ADMIN]
return canonical
logger.error("Built-in tool %r has no canonical capability inventory", name)
return [Capability.SYSTEM_ADMIN]
if name in DEFAULT_TOOL_CAPABILITIES:
canonical = list(DEFAULT_TOOL_CAPABILITIES[name])
# Third-party tools that collide with a privileged name retain its
# security floor. Reviewed-safe names are safe only for their in-tree
# implementation and therefore fail closed on foreign provenance.
return canonical or [Capability.SYSTEM_ADMIN]
return []
__all__ = [
"AgentPolicy",
"Capability",
"CapabilityGrant",
"CapabilityPolicy",
"canonical_tool_capabilities",
"DEFAULT_TOOL_CAPABILITIES",
]