Permissions¶
Deny-first role × tool authorization. denied_tools is checked first, then mode (a totally ordered READ_ONLY < WORKSPACE_WRITE < FULL_ACCESS), then an optional allowed_tools whitelist.
This module ships configuration-free — define your own roles and tool requirements.
Usage¶
from techrevati.runtime import (
PermissionMode, RolePermissionConfig, PermissionPolicy, PermissionEnforcer,
)
policy = PermissionPolicy(
role_configs={
"writer": RolePermissionConfig(
role="writer",
mode=PermissionMode.FULL_ACCESS,
denied_tools=["dangerous_tool"],
),
"reader": RolePermissionConfig(role="reader", mode=PermissionMode.READ_ONLY),
"reviewer": RolePermissionConfig(
role="reviewer",
mode=PermissionMode.WORKSPACE_WRITE,
allowed_tools=["review_code", "comment"], # whitelist mode
),
},
tool_requirements={
"dangerous_tool": PermissionMode.FULL_ACCESS,
"publish": PermissionMode.FULL_ACCESS,
},
)
enforcer = PermissionEnforcer(policy)
outcome = enforcer.check("writer", "any_tool")
if not outcome.allowed:
raise RuntimeError(outcome.reason)
Resolution order¶
- Deny list. Any tool in
denied_toolsis rejected, regardless of mode. - Mode comparison. If the role's mode is lower than the tool's required mode, reject.
- Allowed list. If
allowed_toolsis set, the tool must be in it. - Default-allow. If none of the above triggers a denial, allow.
A role is identified by its exact name. A name that matches a configured role
only after folding case, Unicode compatibility form (NFKC), or invisible characters,
such as ADMIN when admin is configured, is denied whatever
default_allow_unknown_roles says. Treating it as admin would grant access its
caller was not given, and treating it as unknown could escape admin's deny list.
Tool names match regardless of those spellings, so DELETE and delete followed by
a zero-width space or variation selector are both delete. Homoglyphs from other
scripts, such as a Cyrillic е, stay distinct, so prefer allowed_tools over deny
lists when tool names come from untrusted input. tool_requirements keys that
collide after folding, tool names that are empty after folding, and two role configs
whose names differ only by surrounding whitespace are rejected at construction.
A role with no config at all is denied by default, so a typo in a role name cannot
silently grant every tool. Pass default_allow_unknown_roles=True only where a role is
deliberately allowed everything it is not explicitly denied.
API¶
class PermissionMode(IntEnum): READ_ONLY=1, WORKSPACE_WRITE=2, FULL_ACCESS=3
@dataclass
class RolePermissionConfig:
role: str
mode: PermissionMode
allowed_tools: list[str] | None = None
denied_tools: list[str] = []
class PermissionPolicy:
def __init__(self, role_configs=None, tool_requirements=None): ...
def authorize(role: str, tool_name: str) -> PermissionOutcome
class PermissionEnforcer:
def __init__(self, policy: PermissionPolicy): ...
def check(role: str, tool_name: str) -> PermissionOutcome
def is_allowed(role: str, tool_name: str) -> bool
def filter_tools(role: str, tools: list[Callable]) -> list[Callable]
filter_tools reads tool.__name__ from each callable.
Status¶
permissions is intentionally thin: role × tool only. No argument-level restrictions, no quotas, no time-of-day rules. Compose with your own layer if you need those.