Skip to main content
The Palyra Policy Engine provides a centralized, high-performance authorization layer based on the Cedar policy language. It governs all critical operations within the daemon, including tool execution, skill invocation, and administrative actions. Access control is further extended through the access_control module, which manages principal-based identity, API tokens, and feature flagging.

​
Cedar-Based Policy Engine (palyra-policy)

The palyra-policy crate implements the core authorization logic. It uses a default set of Cedar policies to enforce a “deny-by-default” posture while allowing granular overrides based on the request context.

​
Policy Evaluation Flow

When a component (like the GatewayService) needs to authorize an action, it constructs a PolicyRequest and a PolicyRequestContext. These are passed to the engine, which evaluates them against the loaded PolicySet.
  1. Request Construction: A PolicyRequest is created containing the principal, action, and resource crates/palyra-policy/src/lib.rs#11-15.
  2. Context Enrichment: The PolicyRequestContext provides environmental metadata such as device_id, session_id, and capabilities crates/palyra-policy/src/lib.rs#18-26.
  3. Cedar Evaluation: The engine uses the cedar-policy crate’s Authorizer to match the request against the DEFAULT_POLICY_SRC crates/palyra-policy/src/lib.rs#99-181.
  4. Decision: The result is a PolicyDecision (Allow or DenyByDefault) along with a detailed PolicyExplanation for auditing crates/palyra-policy/src/lib.rs#61-81.

​
Default Policy Rules

The system ships with several hardcoded baseline policies: Sources: crates/palyra-policy/src/lib.rs#1-215

​
Tool Call Policy and Capabilities

The tool_protocol module defines how policies are applied specifically to tool execution. Tools are classified by their Capabilities, which determine the level of sensitivity and the required sandbox enforcement.

​
Tool Capability Classification

Tools are associated with ToolCapability variants crates/palyra-daemon/src/tool_protocol.rs#47-52:
  • ProcessExec: Execution of native binaries.
  • Network: Egress to external hosts.
  • SecretsRead: Access to the Palyra Vault.
  • FilesystemWrite: Modifications to the workspace.

​
Sensitivity and Approval

A tool is considered “sensitive” if it possesses any capability listed in SENSITIVE_CAPABILITY_POLICY_NAMES crates/palyra-daemon/src/tool_protocol.rs#148-149. If a tool is sensitive, the ToolDecision will often require approval_required: true, triggering a manual user intervention in the Web Console crates/palyra-daemon/src/tool_protocol.rs#29-34. Sources: crates/palyra-daemon/src/tool_protocol.rs#19-150

​
Access Control and Principal Authorization

The access_control module in palyra-daemon manages identity persistence and API-level permissions. It uses an AccessRegistry stored in access_registry.json to track tokens and roles crates/palyra-daemon/src/access_control.rs#13-14.

​
Identity and Roles

Palyra uses a Role-Based Access Control (RBAC) model defined by WorkspaceRole crates/palyra-daemon/src/access_control.rs#76-80:
  • Owner: Full access, including trust.operate and workspace.manage.
  • Admin: Management of tokens and memberships.
  • Operator: Usage-only access (chat, memory, routines).

​
API Token Lifecycle

Tokens are issued with specific scopes and a principal identifier crates/palyra-daemon/src/access_control.rs#151-173. When a request arrives via the compat (OpenAI-compatible) API, the daemon:
  1. Extracts the token from the Authorization header.
  2. Validates the hash against ApiTokenRecord::token_hash_sha256 crates/palyra-daemon/src/access_control.rs#155.
  3. Checks if the token has the required permission (e.g., PERMISSION_COMPAT_CHAT_CREATE) crates/palyra-daemon/src/transport/http/handlers/compat.rs#134-142.
Sources: crates/palyra-daemon/src/access_control.rs#1-135, crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-130

​
Implementation Diagrams

​
Logic Flow: Tool Authorization to Execution

This diagram bridges the Natural Language concept of “Authorizing a Tool” to the specific code entities involved in the decision and execution pipeline. Sources: crates/palyra-daemon/src/tool_protocol.rs#20-65, crates/palyra-policy/src/lib.rs#211-215, crates/palyra-daemon/src/sandbox_runner.rs#147-151

​
Data Flow: Principal-Based Access Control

This diagram maps the authentication of a request to the internal registry and permission sets. Sources: crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-142, crates/palyra-daemon/src/access_control.rs#13-103

​
Sandbox Enforcement

For tools requiring ProcessExec capabilities, the sandbox_runner applies strict resource constraints.
ConstraintImplementation DetailSource
Executable DenylistPrevents shells (bash, pwsh) and interpreters (python, node) unless explicitly allowed.crates/palyra-daemon/src/sandbox_runner.rs#30-44
Workspace ScopingValidates that all file arguments stay within the workspace_root.crates/palyra-daemon/src/sandbox_runner.rs#175-180
Egress ControlEgressEnforcementMode (None, Preflight, Strict) filters network requests.crates/palyra-daemon/src/sandbox_runner.rs#47-62
Resource QuotasEnforces cpu_time_limit_ms, memory_limit_bytes, and max_output_bytes.crates/palyra-daemon/src/sandbox_runner.rs#90-92
Sources: crates/palyra-daemon/src/sandbox_runner.rs#1-227