Skip to main content
This page documents the Palyra authorization framework, which governs how tools are proposed, evaluated against security policies, and explicitly approved by operators. The system integrates the Cedar Policy Engine for fine-grained access control with a robust human-in-the-loop approval workflow.

​
Cedar-Based Policy Engine

Palyra uses the Cedar policy language to define and enforce authorization rules. The core logic resides in the palyra-policy crate, which provides a safe wrapper around the Cedar Authorizer.

​
Key Components

​
Default Policy Logic

The system initializes with a DEFAULT_POLICY_SRC that enforces baseline security invariants crates/palyra-policy/src/lib.rs#99-187:
  1. Deny Sensitive: Forbids actions flagged as sensitive unless allow_sensitive_tools is true crates/palyra-policy/src/lib.rs#100-105.
  2. Allow Read-Only: Permits non-mutating actions like tool.list or daemon.status crates/palyra-policy/src/lib.rs#107-118.
  3. Allowlisted Execution: Permits tool.execute only if the tool is allowlisted and the principal/channel are authorized crates/palyra-policy/src/lib.rs#120-127.

​
Data Flow: Policy Evaluation

The following diagram illustrates how natural language tool requests are transformed into structured Cedar entities for evaluation. Cedar Authorization Flow Sources: [crates/palyra-policy/src/lib.rs#217-230](http://crates/palyra-policy/src/lib.rs#217-230), [crates/palyra-daemon/src/application/tool_security.rs#19-22](http://crates/palyra-daemon/src/application/tool_security.rs#19-22) (implied context).

​
Tool Decision & Attestation

Every tool call undergoes a multi-stage validation process before execution.

​
decide_tool_call

The decide_tool_call function (referenced in tool_protocol.rs) determines if a tool execution should proceed. It checks:
  1. Tool Budget: Ensures the run has not exceeded max_calls_per_run crates/palyra-daemon/src/tool_protocol.rs#22-23.
  2. Allowlist: Verifies the tool is in the allowed_tools list [crates/palyra-daemon/src/tool_protocol.rs#21].
  3. Capability Check: Maps tools to sensitive capabilities (e.g., ProcessExec, Network) crates/palyra-daemon/src/tool_protocol.rs#47-52.

​
Tool Attestation

Once executed, the system generates a ToolAttestation record. This provides a cryptographic and operational audit trail of the execution crates/palyra-daemon/src/tool_protocol.rs#73-80:
  • execution_sha256: Hash of the execution artifact or input.
  • executor: The runtime used (e.g., sandbox_tier_b, wasmtime).
  • sandbox_enforcement: The specific mode (e.g., strict, preflight).

​
Sensitive Action Approval Workflow

When a tool is deemed “sensitive” or requires explicit authorization by policy, the daemon pauses execution and initiates an approval workflow.

​
Workflow Steps

  1. Proposal Evaluation: evaluate_tool_proposal_security identifies if proposal_approval_required is true crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134.
  2. Pending Approval Creation: build_pending_tool_approval generates a Ulid-based approval_id and a human-readable ApprovalPromptRecord crates/palyra-daemon/src/application/approvals/mod.rs#100-135.
  3. Operator Notification: The request is sent to the operator (via gRPC RunStream or Web Console) crates/palyra-daemon/src/application/run_stream/tool_flow.rs#136-146.
  4. Resolution: The operator selects a decision_scope (Once or Session) crates/palyra-daemon/src/application/approvals/mod.rs#156-183.
  5. Dispatch: apply_tool_approval_outcome updates the ToolDecision based on the operator’s response crates/palyra-daemon/src/application/approvals/mod.rs#32-64.

​
Approval Flow Architecture

This diagram bridges the user-facing “Approval UI” to the internal GatewayRuntimeState. Approval Resolution Loop Sources: [crates/palyra-daemon/src/application/run_stream/tool_flow.rs#212-228](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#212-228), [crates/palyra-daemon/src/application/approvals/mod.rs#67-85](http://crates/palyra-daemon/src/application/approvals/mod.rs#67-85).

​
Tool Policy Snapshot

To ensure auditability, Palyra captures a ToolCallPolicySnapshot for every execution. This snapshot serializes the exact security configuration at the moment of the call, including sandbox tiers and egress rules.
FieldDescriptionSource
allowed_toolsList of tools permitted for the agent.[tool_protocol.rs#153](http://tool_protocol.rs#153)
process_runner.tierSandbox tier (B or C) enforced.[tool_protocol.rs#158](http://tool_protocol.rs#158)
process_runner.egress_enforcement_modeMode of network isolation (None, Preflight, Strict).[tool_protocol.rs#162-166](http://tool_protocol.rs#162-166)
wasm_runtime.fuel_budgetExecution units allowed for WASM tools.[tool_protocol.rs#177](http://tool_protocol.rs#177)
Sources: [crates/palyra-daemon/src/tool_protocol.rs#91-127](http://crates/palyra-daemon/src/tool_protocol.rs#91-127), [crates/palyra-daemon/src/tool_protocol.rs#151-186](http://crates/palyra-daemon/src/tool_protocol.rs#151-186).