> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cedar Policy Engine and Access Control

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/web/src/console/sections/access/AccessControlWorkspace.tsx
  * crates/palyra-daemon/src/access\_control.rs
  * crates/palyra-daemon/src/application/approvals/mod.rs
  * crates/palyra-daemon/src/application/route\_message/tool\_flow\.rs
  * crates/palyra-daemon/src/application/tool\_security.rs
  * crates/palyra-daemon/src/execution\_backends.rs
  * crates/palyra-daemon/src/transport/http/handlers/compat.rs
  * crates/palyra-daemon/tests/golden/compat\_embeddings\_degraded.json
  * crates/palyra-daemon/tests/golden/compat\_embeddings\_feature\_disabled.json
  * crates/palyra-daemon/tests/golden/compat\_embeddings\_response.json
  * crates/palyra-daemon/tests/golden/compat\_model\_detail.json
  * crates/palyra-daemon/tests/golden/compat\_model\_detail\_not\_found.json
  * crates/palyra-daemon/tests/golden/compat\_tools\_invoke\_feature\_disabled.json
  * crates/palyra-policy/src/lib.rs
</details>

Palyra employs a **deny-by-default** security architecture powered by the [Cedar policy language](https://www.cedarpolicy.com/). Every action within the system—from tool execution to API access—must be explicitly permitted by a policy. The system combines static Cedar policies with a dynamic **Approval Gate** system for sensitive operations, ensuring a fail-closed posture where any engine error or missing permission results in an access denial [crates/palyra-policy/src/lib.rs#1-6](http://crates/palyra-policy/src/lib.rs#1-6).

## Cedar Authorization Core

The `palyra-policy` crate serves as the central evaluation engine. It translates system requests into Cedar entities and evaluates them against an embedded baseline policy set [crates/palyra-policy/src/lib.rs#160-161](http://crates/palyra-policy/src/lib.rs#160-161).

### Policy Request and Context

Authorization is triggered via a `PolicyRequest`, which defines the triple of `principal`, `action`, and `resource` [crates/palyra-policy/src/lib.rs#19-26](http://crates/palyra-policy/src/lib.rs#19-26). This is augmented by a `PolicyRequestContext` containing environmental metadata:

| Field          | Description                                                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device_id`    | The originating hardware identifier [crates/palyra-policy/src/lib.rs#36-36](http://crates/palyra-policy/src/lib.rs#36-36).                           |
| `channel`      | The communication platform (e.g., Discord, Slack) [crates/palyra-policy/src/lib.rs#37-38](http://crates/palyra-policy/src/lib.rs#37-38).             |
| `session_id`   | Correlation ID for the current conversation [crates/palyra-policy/src/lib.rs#39-40](http://crates/palyra-policy/src/lib.rs#39-40).                   |
| `capabilities` | Specific permissions requested by a tool (e.g., `net.egress`) [crates/palyra-policy/src/lib.rs#47-49](http://crates/palyra-policy/src/lib.rs#47-49). |

### Authorization Data Flow

The following diagram illustrates how a tool proposal is transformed from a code entity into a Cedar decision.

**Diagram: Tool Proposal to Cedar Evaluation**

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        UserMsg["User: 'Run the build script'"]
    end

    subgraph "Code Entity Space (palyra-daemon)"
        Proposal["ToolProposal (palyra.process.run)"]
        SecurityEval["evaluate_tool_proposal_security()"]

        subgraph "palyra-policy"
            PReq["PolicyRequest"]
            PContext["PolicyRequestContext"]
            CedarEngine["cedar_policy::Authorizer"]
            Baseline["Embedded Baseline Policies"]
        end
    end

    UserMsg --> Proposal
    Proposal --> SecurityEval
    SecurityEval --> PReq
    SecurityEval --> PContext
    PReq & PContext & Baseline --> CedarEngine
    CedarEngine --> Decision["PolicyDecision (Allow/Deny)"]
```

**Sources:** [crates/palyra-daemon/src/application/tool\_security.rs#57-64](http://crates/palyra-daemon/src/application/tool_security.rs#57-64), [crates/palyra-policy/src/lib.rs#12-26](http://crates/palyra-policy/src/lib.rs#12-26), [crates/palyra-daemon/src/application/tool\_security.rs#107-116](http://crates/palyra-daemon/src/application/tool_security.rs#107-116)

## Tool Posture and Execution Gates

Tool execution is governed by a multi-stage pipeline. Before a tool runs, it must pass through the `evaluate_tool_proposal_security` function [crates/palyra-daemon/src/application/tool\_security.rs#107-116](http://crates/palyra-daemon/src/application/tool_security.rs#107-116).

### Posture States

Palyra defines three primary postures for tools:

1. **AlwaysAllow**: Tool executes immediately if Cedar permits.
2. **AskEachTime**: Tool requires an explicit operator approval via the Approval Gate [crates/palyra-daemon/src/application/approvals/mod.rs#1-7](http://crates/palyra-daemon/src/application/approvals/mod.rs#1-7).
3. **Disabled**: Tool is blocked regardless of Cedar policies.

### Sensitive Actions

Certain actions are hardcoded as sensitive and always require elevated permissions or approvals:

* `cron.delete`: Deleting scheduled routines [crates/palyra-policy/src/lib.rs#76-76](http://crates/palyra-policy/src/lib.rs#76-76).
* `memory.purge`: Clearing agent memory [crates/palyra-policy/src/lib.rs#76-76](http://crates/palyra-policy/src/lib.rs#76-76).
* **Skill Execution**: Running Wasm-based plugins via `palyra.plugin.run` [crates/palyra-daemon/src/application/tool\_security.rs#89-95](http://crates/palyra-daemon/src/application/tool_security.rs#89-95).

## Approval Gate System

The Approval Gate handles "human-in-the-loop" security. When a tool call is permitted by Cedar but marked as `approval_required`, the daemon halts execution and creates a `PendingToolApproval` [crates/palyra-daemon/src/application/approvals/mod.rs#40-45](http://crates/palyra-daemon/src/application/approvals/mod.rs#40-45).

### Approval Workflow

1. **Context Assembly**: The system builds a `PendingToolApproval` containing a summary of the request, risk levels, and execution context (e.g., which backend will run the command) [crates/palyra-daemon/src/application/approvals/mod.rs#143-164](http://crates/palyra-daemon/src/application/approvals/mod.rs#143-164).
2. **Journaling**: The request is appended to the `JournalStore` as an `ApprovalPromptRecord` [crates/palyra-daemon/src/application/approvals/mod.rs#26-27](http://crates/palyra-daemon/src/application/approvals/mod.rs#26-27).
3. **Operator Decision**: The operator grants or denies the request via the Web Console or CLI.
4. **Decision Application**: `apply_tool_approval_outcome` merges the operator's decision into the final `ToolDecision`. If the approval channel is unavailable, the system fails closed and denies the request [crates/palyra-daemon/src/application/approvals/mod.rs#65-81](http://crates/palyra-daemon/src/application/approvals/mod.rs#65-81).

**Diagram: Approval Gate Logic**

```mermaid theme={null}
graph TD
    subgraph "palyra-daemon"
        Decision["ToolDecision (allowed=true, approval_required=true)"]
        Apply["apply_tool_approval_outcome()"]
        Outcome{"ToolApprovalOutcome?"}
        Grant["Allow Execution"]
        Deny["Deny (Fail-Closed)"]
    end

    subgraph "Journal / UI"
        Prompt["ApprovalPromptRecord"]
        UserAction["Operator: Approve/Deny"]
    end

    Decision --> Apply
    Apply --> Prompt
    Prompt --> UserAction
    UserAction --> Outcome
    Outcome -- "Approved" --> Grant
    Outcome -- "Denied" --> Deny
    Outcome -- "Timeout/Error" --> Deny
```

**Sources:** [crates/palyra-daemon/src/application/approvals/mod.rs#65-97](http://crates/palyra-daemon/src/application/approvals/mod.rs#65-97), [crates/palyra-daemon/src/application/approvals/mod.rs#168-172](http://crates/palyra-daemon/src/application/approvals/mod.rs#168-172)

## Service Authorization and API Tokens

Access to the daemon's external API (including the OpenAI-compatible compat facade) is managed by the `AccessRegistry` [crates/palyra-daemon/src/access\_control.rs#1-8](http://crates/palyra-daemon/src/access_control.rs#1-8).

### Feature Flags and RBAC

The system uses feature flags to gate entire subsystems:

* `compat_api`: Gates the OpenAI-compatible HTTP handlers [crates/palyra-daemon/src/access\_control.rs#34-34](http://crates/palyra-daemon/src/access_control.rs#34-34).
* `api_tokens`: Gates the issuance and use of scoped tokens [crates/palyra-daemon/src/access\_control.rs#40-40](http://crates/palyra-daemon/src/access_control.rs#40-40).
* `rbac`: Enables role-based access checks [crates/palyra-daemon/src/access\_control.rs#44-44](http://crates/palyra-daemon/src/access_control.rs#44-44).

### Workspace Roles

Permissions are grouped into `WorkspaceRole` levels [crates/palyra-daemon/src/access\_control.rs#114-118](http://crates/palyra-daemon/src/access_control.rs#114-118):

* **Owner**: Full authority, including trust and rollout management [crates/palyra-daemon/src/access\_control.rs#148-150](http://crates/palyra-daemon/src/access_control.rs#148-150).
* **Admin**: Membership and API token management [crates/palyra-daemon/src/access\_control.rs#148-149](http://crates/palyra-daemon/src/access_control.rs#148-149).
* **Operator**: Baseline session and memory usage [crates/palyra-daemon/src/access\_control.rs#148-148](http://crates/palyra-daemon/src/access_control.rs#148-148).

### API Token Scopes

Tokens are minted with specific scopes (e.g., `compat.chat.create`) and are subject to rate limiting [crates/palyra-daemon/src/access\_control.rs#53-60](http://crates/palyra-daemon/src/access_control.rs#53-60). Tokens only store SHA-256 digests of the secret to prevent credential leakage from the state file [crates/palyra-daemon/src/access\_control.rs#10-11](http://crates/palyra-daemon/src/access_control.rs#10-11).

**Sources:** [crates/palyra-daemon/src/access\_control.rs#1-67](http://crates/palyra-daemon/src/access_control.rs#1-67), [crates/palyra-daemon/src/transport/http/handlers/compat.rs#162-169](http://crates/palyra-daemon/src/transport/http/handlers/compat.rs#162-169)