policy

Embeds the Praxis Policy Engine in-process to enforce multi-source identity, APL route policy, RFC 8693 token exchange, field redaction, session taint, audit emission, and (under body_access: read_write) request / response body rewriting. Content scanning is a host plugin the engine dispatches, not a bundled one.

Requires Cargo feature: policy-engine.

Configuration Notes

Registered under the YAML filter name policy. The policy-engine cargo feature is on by default; --no-default-features leaves the filter out.

A single request can carry multiple identity sources — user JWT in Authorization, agent JWT in X-Agent-Token, workload JWT in X-Workload-Token, etc. Each registered identity plugin reads its own configured header and contributes to a typed Extensions context.

On the body phase, the filter consumes protocol classifier filter metadata (from the praxis-ai package) to dispatch the matching CMF hook chain. APL routes (declared in the policy document) gate the tool/prompt/resource call by role, attribute, or Cedar PDP decision. delegate(...) steps mint audience-scoped tokens (RFC 8693) that the allow path attaches as upstream headers.

Policies with llm: routes authorize the top-level request model through cmf.llm_input, without classifier metadata. Missing, unlisted, and ambiguous models fail closed by default.

OPA, CEL, and Cedar pre_invocation steps on llm: routes also read the parsed request body as llm.request (input.llm.request in OPA, context.llm.request in Cedar), so a rule can inspect tools, messages, or input. Only a request attributed to a model carries it: a JSON body with a usable top-level model, no JSON-RPC envelope, and no mcp.method metadata. Other requests carry none. CEL and Cedar deny when a rule reads it, and so does an OPA boolean or object decision, but an OPA deny set needs its own guard. On allow the upstream receives the original bytes. A body over llm.max_request_bytes receives HTTP 413 before any authorization rule runs. Policy judges the body as it reaches this filter, so order body-rewriting filters before policy. For rule syntax, engine types, and absent-value behavior, see Structured request input in the policy engine docs.

PPE 0.4.1 changes OPA and CEL args on tool: routes to native JSON. Before upgrading, review rules that read args: for example, a numeric ID in args.ids must be compared with 13, not "13". A schema-backed cedar-direct PDP must set structured_context: true or the policy fails to load. Its schema must also declare the optional args and llm context fields its actions can receive, or those requests are denied. See the PPE 0.4.1 changelog and args migration guidance.

The configured policy receives the full parsed inference request. Treat policy documents and custom plugins as trusted: a rule or an explicit outbound call can disclose fields it reads. Review policy authorship and outbound endpoints before enabling structured request input.

On a policy with llm: routes, any request body without mcp.method metadata that repeats a key within one JSON object, at any depth, including keys that differ only in case, receives HTTP 400 with violation code llm.duplicate_key before any authorization rule runs, since backends disagree on which copy wins. This covers bodies with no model and unclaimed JSON-RPC envelopes too. The response names neither the key nor any value. A body that is not valid JSON is not refused for being malformed: it carries no usable model, so it is handled like any other body without one.

A lone differently cased field such as Tools is not a duplicate. llm.request keeps the wire spelling, so a rule checking only tools will not see Tools. If an upstream accepts such aliases, cover them explicitly in policy or require canonical field spelling at its boundary.

The CMF prompt text that APL steps and scanners read is projected from system, Responses instructions, messages[].content, legacy prompt, and input. For Responses and embeddings input, only text counts: a string, string items, and input_text, text, output_text, reasoning_text, or summary_text parts. Message items contribute their content. Every other item type, including tool calls, tool outputs, and reasoning, contributes its arguments, input, output, text, content, and summary. File search result text, code interpreter code and output logs, and listed MCP tool description are also projected. Token-ID arrays, images, and files are skipped.

body_access: read_write enables the JSON-RPC re-serialization round-trip so APL field mutators (redact(), assign()) rewrite the upstream request body and the downstream response. It also enables cmf.llm_output for non-streaming inference responses. APL field mutators do not rewrite inference bodies.

body_access: read_write also enables response-phase tool:, prompt:, and resource: rules, including attribute-only post_invocation rules. Under read_only, these rules are skipped and a warning is emitted. A response-only route adds no request-phase route rule; identity checks and global policy still apply.

result.<field> projection for prompt: and resource: routes remains blocked on policy #75; host-side content projection is tracked in Praxis #1330. A result: field pipeline on either entity, including an inherited one, is rejected at load so its controls cannot be silently skipped.

Policies with MCP entity routes cannot declare authorization: on an http: route. Use global for shared authorization; route-scoped authentication: remains supported.

Response-body hooks run on a small dedicated runtime while the worker waits, for at most twice the engine’s per-plugin timeout (engine_settings.plugin_timeout, so 60 seconds by default). A hook that does not finish in time is aborted and the response fails under the filter’s failure_mode: closed truncates the response, open passes the body through unfiltered.

Outbound policy calls share the proxy’s sub-request limits and circuit breaker, use HTTP/1.1, and keep a separate 1 MiB response ceiling. Calls made by response-body hooks use their own pool on the dispatch runtime, with the same connection limit but no circuit breaker. TLS uses the platform trust store; cluster private CAs and client certificates do not apply. A private destination requires trusted_private_endpoints for a specific host, or allow_private_idp to relax every callout.

An endpoint URL may name an IP address over http, but not over https: an IP carries no SNI, and Pingora peers skip certificate verification entirely when SNI is empty. Use a hostname for https.

Praxis filter configs are flat: the filter’s typed fields sit directly under the - filter: entry alongside the structural keys (name, conditions), not nested under a config: wrapper. See examples/configs/security/policy.yaml for a runnable example.

The referenced YAML is the policy document — plugins, routes, and identity-source declarations. The filter loads it once at construction and rejects misconfigured policy at server startup (fail-fast rather than at first request).

Configuration

Example

filter: policy
config_path: /etc/praxis/policy.yaml
body_access: read_write       # optional; default read_only
require_protocol_metadata: true    # optional; default true
init_timeout_secs: 30         # optional; default 30
max_buffer_bytes: 10485760
llm:
  require_model: true
  require_route: true
  provider: openai