palyra-policy crate provides a unified authorization layer for the Palyra platform by wrapping the Cedar Policy Language. It enforces a strict deny-by-default posture for all system actions, including tool executions, skill invocations, and sensitive administrative operations.
Architecture and Data Flow
The policy engine operates by transforming system state and request metadata into Cedar-compatible entities and context. It evaluates these against a pre-defined set of policies to reach a binary decision (Allow or Deny).
Request Transformation Flow
The following diagram illustrates how natural language-like system concepts (Principals, Actions) are mapped to code entities and processed by the engine. System Concept to Code Entity Mapping Sources: crates/palyra-policy/src/lib.rs#10-38, crates/palyra-policy/src/lib.rs#217-250Key Data Structures
PolicyRequest
Represents the core “Who, What, Where” of an authorization check.principal: The identity requesting the action (e.g., a user ID or device ID) crates/palyra-policy/src/lib.rs#12.action: The operation being performed (e.g.,tool.execute,vault.get) crates/palyra-policy/src/lib.rs#13.resource: The target of the action crates/palyra-policy/src/lib.rs#14.
PolicyRequestContext
Provides supplemental metadata used by Cedarwhen clauses to make fine-grained decisions.
capabilities: A list of strings representing what the tool or skill is capable of (e.g.,process_exec,network) crates/palyra-policy/src/lib.rs#25.tool_name/skill_id: Specific identifiers for the logic being invoked crates/palyra-policy/src/lib.rs#23-24.is_sensitive_action: Boolean flag derived from thesensitive_actionslist crates/palyra-policy/src/lib.rs#242.
PolicyEvaluationConfig
Static configuration that governs the baseline behavior of the engine, such as which tools are globally allowlisted or which actions require elevated gating crates/palyra-policy/src/lib.rs#29-38.Implementation Detail: evaluate_with_context
The core logic resides in evaluate_with_context crates/palyra-policy/src/lib.rs#217-250. This function performs the following steps:
- Context Construction: It builds a
serde_json::Valuecontaining environment attributes likeis_allowlisted_tool,is_sensitive_action, andis_tool_execute_principal_allowedcrates/palyra-policy/src/lib.rs#226-248. - Entity Mapping: It maps the
PolicyRequeststrings into CedarEntityUidtypes (e.g.,Principal::"...",Action::"...",Resource::"...") crates/palyra-policy/src/lib.rs#252-257. - Cedar Invocation: It calls the
cedar_policy::Authorizerwith the constructed request, entities, and the default policy set crates/palyra-policy/src/lib.rs#264-270.
Default Policy Set
The engine uses a hardcodedDEFAULT_POLICY_SRC crates/palyra-policy/src/lib.rs#99-187 that defines the platform’s security boundaries:
| Policy ID | Purpose | Logic |
|---|---|---|
deny_sensitive_without_approval | Sensitive Gating | Forbids actions if context.is_sensitive_action is true and allow_sensitive_tools is false crates/palyra-policy/src/lib.rs#100-105. |
allow_read_only_actions | Auditability | Permits non-mutating actions like tool.list or daemon.status crates/palyra-policy/src/lib.rs#107-118. |
allow_allowlisted_tool_execute | Execution Control | Permits tool.execute only if the tool, principal, and channel are all allowlisted crates/palyra-policy/src/lib.rs#120-127. |
allow_vault_actions | Secret Access | Permits vault.put, vault.get, etc crates/palyra-policy/src/lib.rs#159-166. |
Tool Capability and Sensitive Action Gating
Palyra classifies certain tool capabilities as “sensitive,” which triggers additional enforcement logic in thepalyra-daemon.
Tool Execution Security Flow
Sources: crates/palyra-daemon/src/tool_protocol.rs#47-64, crates/palyra-daemon/src/tool_protocol.rs#148-149, crates/palyra-policy/src/lib.rs#100-105
Sensitive Actions
The platform defines a set ofDEFAULT_SENSITIVE_ACTIONS that are always gated, including:
cron.deletememory.deletememory.purge
deny_sensitive_without_approval policy unless the PolicyEvaluationConfig explicitly enables allow_sensitive_tools crates/palyra-policy/src/lib.rs#40-53.
Integration with Sandbox and Plugins
The policy engine is consumed by thetool_protocol in the daemon to decide if a tool can even attempt execution:
- Pre-flight Check: Before spawning a
run_constrained_process(Sandbox Tier B/C) orrun_wasm_plugin, the daemon callsevaluate_with_contextcrates/palyra-daemon/src/tool_protocol.rs#3-6. - Context Injection: The daemon populates the
PolicyRequestContextwith therun_id,session_id, and the specificToolCapabilityrequirements of the tool (e.g.,ToolCapability::ProcessExec) crates/palyra-daemon/src/tool_protocol.rs#134. - Fail-Closed: If the
PolicyDecisionisDenyByDefault, the execution is aborted immediately with a diagnostic reason crates/palyra-policy/src/lib.rs#189-198.