Architecture and Data Flow
The policy engine operates as a request-response system. When a component (e.g., theGatewayService or ToolCallHandler) needs to verify an action, it constructs a PolicyRequest and a PolicyRequestContext. These are then evaluated against a PolicySet containing Cedar policies.
Policy Evaluation Flow
Sources: crates/palyra-policy/src/lib.rs#217-250, crates/palyra-daemon/src/tool_protocol.rs#3-10Key Data Structures
PolicyRequest and Context
The engine uses three primary structures to define the authorization boundary:| Structure | Role | Key Fields |
|---|---|---|
PolicyRequest | The “Triple” of the request | principal, action, resource |
PolicyRequestContext | Environment/Execution data | device_id, run_id, capabilities, tool_name |
PolicyEvaluationConfig | Runtime allowlists | allowlisted_tools, sensitive_actions, tool_execute_channel_allowlist |
Cedar Policy Implementation
Palyra ships with aDEFAULT_POLICY_SRC that defines the baseline security posture. This includes “Deny by Default” logic and specific permits for core operations.
Baseline Policy Logic
- Sensitive Actions: Actions like
cron.deleteormemory.purgeare blocked unlessallow_sensitive_toolsis explicitly true crates/palyra-policy/src/lib.rs#100-105. - Read-Only Operations: Generic status and list actions (e.g.,
tool.list,daemon.status) are permitted globally crates/palyra-policy/src/lib.rs#107-118. - Tool Execution: Requires the tool to be in the
allowlisted_toolset and the principal/channel to be authorized crates/palyra-policy/src/lib.rs#120-127.
AccessRegistry and Feature Flags
TheAccessRegistry manages the persistence of identity-linked permissions, API tokens, and feature flags. It is stored in access_registry.json crates/palyra-daemon/src/access_control.rs#13-14.
Feature Flags and RBAC
The system uses feature flags to toggle advanced authorization modes:FEATURE_TEAM_MODE: Enables multi-user collaboration crates/palyra-daemon/src/access_control.rs#20.FEATURE_RBAC: Enables Role-Based Access Control crates/palyra-daemon/src/access_control.rs#21.- Workspace Roles: Defines
Owner,Admin, andOperator, each with a hardcoded set of permissions crates/palyra-daemon/src/access_control.rs#76-135.
Integration with Tool Execution
The policy engine is tightly coupled with theSandboxProcessRunner. Before a tool is executed, the ToolCallConfig determines the sandbox tier and egress enforcement mode.
Egress Enforcement Modes
- None: No network restrictions.
- Preflight: Checks requested hosts against an allowlist before spawning.
- Strict: Enforces network isolation at the OS level (e.g., via
bwrap --unshare-net) crates/palyra-daemon/src/sandbox_runner.rs#47-62.
Mapping System Logic to Code Entities
Sources: crates/palyra-policy/src/lib.rs#11-38, crates/palyra-daemon/src/access_control.rs#186-200, crates/palyra-daemon/src/sandbox_runner.rs#81-93API Token Management
TheAccessRegistry handles ApiTokenRecord structures, which are used for the OpenAI-compatible “Compat API” crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126. These tokens are hashed using SHA-256 before storage crates/palyra-daemon/src/access_control.rs#155.
| Feature | Code Reference |
|---|---|
| Token Rate Limiting | DEFAULT_TOKEN_RATE_LIMIT_PER_MINUTE crates/palyra-daemon/src/access_control.rs#16 |
| Scope Validation | MissingScope Error crates/palyra-daemon/src/access_control.rs#71 |
| Token Rotation | rotated_from_token_id crates/palyra-daemon/src/access_control.rs#172 |
Sandbox Tier Policy
Policy decisions also dictate the sandbox “Tier” used for execution:- Tier B: In-process constrained execution (Unix-only resource controls) crates/palyra-daemon/src/sandbox_runner.rs#159-165.
- Tier C: External process isolation using
linux_bubblewrapormacos_sandbox_execcrates/palyra-sandbox/src/lib.rs#8-13.