Praxis Policy Engine Documentation

PPE is a typed policy runtime for AI middleware.
On this page

PPE is a typed policy runtime for AI middleware. It maps tools, resources, prompts, inference calls, and conventional APIs to routes by entity type and name. PPE combines global defaults, matching groups, and route controls into phases that validate inputs, authorize operations, apply effects, and transform results. The pipeline controls which operations run, what data returns, and where it may flow.

Agent operations pass through PPE policy, effects, plugins, and enforcement. Policy reads verified identity from an IdP and labels from a session store.

Before policy evaluation, PPE verifies the caller with the IdP and maps subject, role, and permission claims into attributes. The Policy stage evaluates predicates and invokes CEL, Cedar, or OPA where configured. Effects can redact data, request approval, apply session taint, or perform token exchange / delegation for an audience-scoped upstream credential. The session store carries information-flow labels across calls. PPE records the delegation chain and audit history.

Why it exists

  • Vision: the Reference Monitor model and where PPE sits in an agent stack
  • Threat Model: the adversary, the trust boundary, and what each placement defends

Getting started

  • Quick Start: stand up an enforcement point and run your first policy
  • Overview: how it works, followed through one scenario end to end
  • Use Cases: the controls running behind a real gateway

Writing policy

  • APL: routes, phases, predicates, rules, and field pipelines
  • Grammar: the normative grammar; where it and the parser disagree, one is a bug
  • Effects and Sequencing: the effect catalog, halt-on-deny, sequential and parallel composition
  • PDP Integration: handing a decision to Cedar, CEL, or OPA
  • Identity: resolving a caller and what lands in the attribute bag
  • Static Attributes: operator-maintained facts read under data.*
  • Delegation: token exchange, delegation subjects, and token caching
  • Elicitation: human in the loop, and the suspend and resume model
  • Session Taint: information flow labels that outlive a single call
  • Backend Restriction: constraining where a call is allowed to land

Configuring and operating

  • Configuration: the config document, its five top-level keys, and both dispatch modes
  • HTTP Routing: the http: route selector, precedence, and the catch-all report
  • Identity and Delegation: inbound identity slots, outbound delegation subjects, and six recipes
  • Identity Claim Mapping: adding and testing a provider-specific JWT claim mapper preset
  • Header Assertions: projecting derived identity onto upstream requests
  • Deployment: the same policy at a gateway, a sidecar, or in-framework
  • Patterns: layered enforcement, shadow rollout, guardrails, least privilege
  • Upgrading APL: every key and form an existing configuration must rewrite

Architecture

Reference

  • Crates: what each crate in the workspace is for
  • Builtins: bundled plugins, decision points, session stores, and their features
  • Testing: testing a policy as code
  • Benchmarks: measuring the decision hot path, and reading the results
A Reference Monitor for Agents

PPE acts as a reference monitor between an agent and the tools, agents, and data it can access.

APL: configuring enforcement pipelines

APL (Authorization Policy Layer) defines PPE enforcement pipelines.

assertions: Wire Contract

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2026 Praxis Contributors –>

Benchmarks

PPE ships a Criterion suite that measures the decision hot path: plugin dispatch, a full route decision, per-PDP evaluation, throughput under concurrency, and heap use per decision.

Builtins

PPE ships a set of plugins, decision points, and a session store, each behind a Cargo feature.

CMF extensions and the attribute bag

Map typed Common Message Format extensions into the attribute bag that APL policies inspect.

Common Message Format

APL evaluates policy against a request in the Common Message Format (CMF).

Configuration

A PPE configuration is one YAML document. It declares the plugins the process can reach, the cross-cutting wiring, and the policy that decides which of them run for a given operation.

Crate Reference

PPE is a Cargo workspace. Most hosts depend on praxis-policy, the facade, and nothing else: it re-exports the runtime and, behind features, the bundled extensions.

Deployment

PPE is the enforcement point, but where that point sits is your choice.

Extensions and Capability-Gating

Alongside the message, every operation carries typed extensions: the contextual state policy reasons about.

How PPE Works

Understand how PPE evaluates identity and APL policy for each operation, then applies effects before allowing it to reach a backend.

How to add a claim mapper preset in PPE

Adding a preset is data-driven; no new mapper implementation or resolver branch is needed.

HTTP Routing

Most routes select an operation by name: a tool:, a resource:, a prompt:, an llm:.

Identity and Token Exchange / Delegation

PPE resolves the inbound caller and mints the outbound credential on every request.

Patterns

These production patterns cover APL authoring and rollout.

Plugins and the Execution Pipeline

APL defines policy. The execution pipeline runs its effects. Write pipeline code only to add an effect through a plugin or inspect effect ordering and execution.

Quick Start

Stand up PPE and run the scenario: a get_employee route that authorizes by role and redacts a field by permission.

Testing Policy

Test APL by loading a policy, driving operations through the runtime, and asserting each outcome. Most route tests need no live backend.

Threat Model

This threat model defines the assumed adversary, the Reference Monitor boundary, and the coverage of each deployment placement.

Upgrading an APL Configuration

Rewrite the keys and forms listed below. Each entry states the old behavior, the replacement, and the load error produced by a missed migration.

Use Cases

Explore end-to-end PPE deployments for AI gateways, identity providers, delegated credentials, and policy enforcement.