Documentation on CPEX Documentation

Vision

Mon, 01 Jan 0001 00:00:00 +0000

A Reference Monitor for Agents#

An agent backed by an LLM acts across trust domains. It calls tools, invokes other agents over A2A, runs inference, and fetches prompts and resources. The model deciding which operation to run is untrusted: it can be steered by injected content, confused by tool output, or simply wrong. Authorization, delegation, and information-flow control cannot live inside that model.

CPEX puts them at the boundary. It is a deterministic reference monitor between the untrusted LLM and the capabilities it invokes. Every operation passes through CPEX, which decides what happens using state the model cannot see or forge.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

How CPEX Works#

A running scenario#

Picture one agent serving several people. It answers questions by calling tools (an HR records service, a code repository, an email sender), invoking other agents over A2A, running inference, and fetching prompts and resources. The backends are shared. The callers are not: an HR analyst, an engineer, and a support rep each drive the same agent with different identities and different entitlements.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

This walks through standing up CPEX as an enforcement point and running the scenario: the get_employee route that authorizes by role and redacts a field by permission.

1. Add CPEX#

cargo add cpex --features builtins

The builtins feature compiles in the bundled plugins and PDPs (JWT identity, OAuth delegation, PII scanner, audit logger, Cedar, CEL). For a smaller build, opt into a granular subset: jwt, cedar, pii, and so on (see Builtins).

Common Message Format

Mon, 01 Jan 0001 00:00:00 +0000

Common Message Format#

APL evaluates policy against a request. The Common Message Format (CMF) is the shape of that request: a protocol-agnostic envelope that represents any mediated operation in one structure, so a single policy can apply across tool calls, A2A methods, inference, prompts, and resources without caring which protocol carried them.

Why a common format#

Without CMF, a redaction policy for tool results and a redaction policy for LLM output are different code against different payload types, even though they do the same thing. CMF gives every interception point the same representation, so cross-cutting policy is written once and evaluated everywhere. This is what lets the same APL field pipeline redact a field whether it arrived in a tool result or a model completion.

Extensions & Capability-Gating

Mon, 01 Jan 0001 00:00:00 +0000

Extensions and Capability-Gating#

Alongside the message, every operation carries typed extensions: the contextual state policy reasons about. Identity is an extension. So are security labels, the delegation chain, request headers, agent session context, and more. Each extension is bridged into the flat attribute bag APL reads, under a well-known namespace. Capability-gating controls which plugins may read or write each one.

This is a supporting concern, not the headline. You rarely configure it directly. It matters because it is what makes least privilege real for the plugins that execute policy effects, and because the namespaces below are the exact keys an APL predicate or plugin can read.

Plugins & Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Plugins and the Execution Pipeline#

APL is the policy surface. The pipeline is what runs underneath it: the mechanism that executes a policy’s effects. Most of the time you write APL and never touch the pipeline directly. You reach for it when you extend the set of effects available to policy, by adding a plugin, or when you need to understand exactly how and when effects run.

Hooks#

A hook is a named interception point. The host invokes a hook at an operation boundary (before a tool call, after an LLM completion, around a prompt or resource fetch), and the plugin manager runs the plugins registered there. Hooks are where APL routes attach: a route’s policy phase runs at the pre-invocation hook, its result phase at the post-invocation hook.

Builtins

Mon, 01 Jan 0001 00:00:00 +0000

Builtins#

CPEX ships a set of builtin plugins, PDP resolvers, and a session store, each behind a Cargo feature. With a feature enabled, cpex::install_builtins registers its factory and APL can reference it by kind.

The catalog#

Kind	Type	Feature	Purpose
`identity/jwt`	identity	`jwt`	Resolve a subject from a verified JWT (see Identity).
`delegator/oauth`	delegator	`oauth`	RFC 8693 token exchange (see Delegation).
`validator/pii-scan`	validator	`pii`	Detect and redact PII in content.
`audit/logger`	audit	`audit`	Append-only decision logging.
`cedar-direct`	PDP resolver	`cedar`	Evaluate Cedar policy (dialect `cedar`).
`cel`	PDP resolver	`cel`	Evaluate CEL expressions (dialect `cel`).
`valkey`	session store	`valkey`	Persist taint labels across processes (see Session Tainting).

The default session store is in-process memory; no feature or kind is needed for it.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

A CPEX config is a single document that declares the plugins and PDP resolvers available, the global settings, and the APL routes. The runtime loads it and the APL visitor wires routes to hooks.

Shape#

plugins: # the plugins available to policy, by kind
 - name: ...
 kind: ...
 hooks: [...]
 capabilities: [...]
 config: { ... }

global: # cross-cutting resolvers and stores
 pdp:
 - kind: ...
 session_store:
 kind: ...

routes: # APL policy, keyed by operation
 <route>:
 args: { ... }
 policy: [ ... ]
 result: { ... }
 post_policy: [ ... ]

Plugins#

Each plugin entry declares how it is identified, where it runs, and what it may see:

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deployment#

CPEX is the enforcement point, but where that point sits is your choice. The same APL policy enforces whether CPEX runs as a gateway in front of a tool server, as an egress sidecar beside an agent, or inside an agent framework. You move the boundary; the policy does not change.

The same policy, any enforcement point#

Take the get_compensation route. It is identical whether CPEX fronts the backend, guards the agent’s egress, or runs inside the agent runtime:

Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Patterns#

Production patterns for writing and rolling out CPEX policy. Each is expressed in APL and builds on the concepts in the earlier pages.

Layered enforcement#

Order effects cheapest-gate-first so expensive work only runs for requests that survive the early checks. Attribute gates, then a PDP call, then delegation:

policy:
 - "require(team.engineering | team.security)" # cheap
 - cedar: { action: 'Action::"read"', resource: { type: Repo, id: ${args.repo_name} } }
 - "delegate(github-oauth, target: github-api, permissions: [repo:read])" # expensive, last

A deny at any layer halts the rest, so you never mint a token for a request a later layer would reject.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Testing Policy#

Policy is code, and it deserves tests. The behaviors worth covering are the ones the scenario demonstrates: a route allows the right callers, denies the wrong ones, and redacts the right fields. Because APL is declarative and evaluated by apl-core, you can test a route by evaluating it against fixture identities and asserting the outcome, without standing up a live backend.

What to test#

For each route, cover the outcomes its policy produces:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Crate Reference#

CPEX is a Cargo workspace of focused crates. Most hosts depend on cpex (the facade); plugin authors depend on cpex-sdk.

Crate	Role
`cpex`	Host facade. Re-exports the runtime and, with a feature, the builtins. Start here.
`cpex-core`	The runtime: `PluginManager`, executor, hooks, config, extensions.
`cpex-sdk`	Plugin author SDK: the `Plugin` and `HookHandler` traits, payloads, results. Depend on this to write a plugin or PDP resolver.
`cpex-orchestration`	Async concurrency primitives shared by the runtime.
`cpex-builtins`	Feature-gated bundle of builtin plugins, PDP resolvers, and the session store (see Builtins).
`cpex-ffi`	C FFI (`cdylib` / `staticlib`) for Go, Python, and WASM host bindings.
`apl-core`	APL compiler and evaluator: rules, effects, field pipelines, routes.
`apl-cmf`	Bridges typed extensions into the flat attribute bag APL reads.
`apl-cpex`	Runtime adapter: wires APL routes to hooks, dispatches plugins and PDPs.

Generated API docs are on docs.rs/cpex.