praxis_policy/

lib.rs

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

//! **PPE is a policy enforcement runtime for AI agents.**
//!
//! It is a deterministic reference monitor between an agent and every
//! capability it invokes: tools, prompts, resources, inference providers, and
//! A2A methods. Each operation runs through a policy-defined pipeline that can
//! resolve identity, make an authorization decision (delegated to an engine
//! like Cedar or CEL), exchange and reduce credentials before a downstream
//! call, redact inputs and outputs, track information flow across calls, and
//! audit. You write that policy declaratively in APL, the configuration that
//! defines each operation's pipeline; PPE evaluates and enforces it at the
//! boundary, against state the model cannot observe or forge.
//!
//! - Source and issues: <https://github.com/praxis-proxy/policy>
//!
//! # This crate
//!
//! `praxis-policy` is the **host facade**: one dependency that re-exports the PPE
//! runtime (`praxis-policy-core`, `praxis-policy-apl-core`, `praxis-policy-apl-cmf`, `praxis-policy-apl-runtime`), so a host depends
//! on this crate instead of pinning each of them separately.
//!
//! By default it is the **engine only**: no builtin plugins are compiled in.
//! The bundled plugins, PDPs and session stores are registered from here, each
//! behind a feature, and only what you enable is compiled.
//!
//! # Usage
//!
//! Engine only (register your own factories):
//!
//! ```no_run
//! use std::sync::Arc;
//! use praxis_policy::PolicyEngine;
//!
//! let mgr = Arc::new(PolicyEngine::default());
//! // ... register host factories, then `praxis_policy_apl_runtime::register_apl(&mgr, opts)`.
//! ```
//!
//! With the bundled builtins (enable the `builtins` feature):
//!
//! ```ignore
//! use std::sync::Arc;
//! use praxis_policy::PolicyEngine;
//!
//! let mgr = Arc::new(PolicyEngine::default());
//! // Register every enabled builtin factory and install the APL config
//! // visitor (in-process defaults) in one call:
//! praxis_policy::install_builtins(&mgr);
//! // ... then load a config that references the enabled `kind`s.
//! ```
//!
//! # Features
//!
//! No plugins are on by default (`praxis-policy` alone is the engine).
//! `builtins` enables every bundled extension, including the Valkey session
//! store; or pick a granular subset (`jwt`, `api-key`, `oauth`, `elicitation-ciba`,
//! `cedar`, `cel`, `opa`, `valkey`, `secrets-vault`). Any of them brings in the registration
//! helpers, and each one re-exports its own concrete factory type here.
//!
//! # Plugins the host supplies
//!
//! A plugin does not have to be bundled. Implement [`PluginFactory`] and hand it
//! to [`PolicyEngine::register_factory`] under the `kind:` your YAML names;
//! [`prelude`] is the surface to write it against. An unrecognised `kind` is a
//! load-time error, so a missing registration fails at startup rather than
//! silently skipping the plugin.
//!
//! `reference/plugins/` in this repository holds two worked examples, a PII
//! scanner and an audit logger. Neither is published or bundled; a host registers
//! them.

// Whole-crate re-exports for advanced use (types not surfaced below).

pub use {
    praxis_policy_apl_cmf, praxis_policy_apl_core, praxis_policy_apl_runtime, praxis_policy_core,
};

pub use praxis_policy_apl_core::step::PdpFactory;
pub use praxis_policy_apl_runtime::{
    AplOptions, DispatchCache, MemorySessionStore, SessionStore, SessionStoreFactory, register_apl,
};
pub use praxis_policy_core::engine::PolicyEngine;

/// The two types a host needs to accept a plugin it did not compile in:
/// [`PolicyEngine::register_factory`] takes a `Box<dyn PluginFactory>`, and
/// [`PluginInstance`] is what that factory returns.
///
/// Surfaced here so a host embedding the engine can name them without reaching
/// through to `praxis_policy_core`. Plugin *authors* get the same two names from
/// [`prelude`].
pub use praxis_policy_core::factory::{PluginFactory, PluginInstance};

/// What a host needs to give the engine its secrets.
///
/// A host builds a [`SecretProviderRegistry`] holding the backends this build
/// carries and installs it with `PolicyEngine::set_secret_providers` before
/// `initialize()`. [`SecretProviderFactory`] is what a host implements to add a
/// backend of its own, and [`SecretRef`] is the handle a consumer keeps so a
/// later refresh reaches it. A consumer that rebuilds something on rotation
/// reads [`SecretRef::snapshot`], which pairs the value with the generation it
/// belongs to.
///
/// `env` and `file` are always registered by
/// [`SecretProviderRegistry::with_builtin_backends`]. Vault KV v2 is behind
/// the `secrets-vault` feature: the host constructs `VaultSecretProviderFactory`
/// with its `HttpTransport` and registers it (or calls `registry_with_vault`).
/// Nothing here spawns a Vault session ticker; token renewal is lazy on
/// the next read.
///
/// There is no handle here that reads every declared value. A host drives
/// refresh with `PolicyEngine::refresh_secrets` and watches for staleness with
/// `PolicyEngine::secrets_last_success`, neither of which yields secret
/// material.
pub use praxis_policy_core::secrets::{
    ProviderFailure, ProviderHealth, RefreshReport, SecretError, SecretProvider,
    SecretProviderFactory, SecretProviderRegistry, SecretRef, SecretSnapshot, SecretsHealth,
};

/// Curated re-exports for plugin authors, so a plugin crate can depend on this
/// facade alone. See [`praxis_policy_core::prelude`].
pub use praxis_policy_core::prelude;

// Concrete factory types + KIND consts, each behind its feature.
#[cfg(feature = "cedar")]
pub use praxis_policy_builtins::pdps::cedar_direct::CedarDirectPdpFactory;
#[cfg(feature = "cel")]
pub use praxis_policy_builtins::pdps::cel::CelPdpFactory;
#[cfg(feature = "opa")]
pub use praxis_policy_builtins::pdps::opa::OpaPdpFactory;
#[cfg(feature = "oauth")]
pub use praxis_policy_builtins::plugins::delegator_oauth::{
    KIND as OAUTH_KIND, OAuthDelegatorFactory,
};
#[cfg(feature = "delegator-vault")]
pub use praxis_policy_builtins::plugins::delegator_vault::{
    KIND as VAULT_DELEGATOR_KIND, VaultDelegatorFactory,
};
#[cfg(feature = "elicitation-ciba")]
pub use praxis_policy_builtins::plugins::elicitation_ciba::{
    CibaApproverFactory, KIND as CIBA_KIND,
};
#[cfg(feature = "api-key")]
pub use praxis_policy_builtins::plugins::identity_api_key::{
    ApiKeyIdentityFactory, KIND as API_KEY_KIND,
};
#[cfg(feature = "jwt")]
pub use praxis_policy_builtins::plugins::identity_jwt::{JwtIdentityFactory, KIND as JWT_KIND};
#[cfg(feature = "experimental-quota")]
pub use praxis_policy_builtins::plugins::quota::{KIND as QUOTA_KIND, QuotaFactory};
#[cfg(feature = "secrets-vault")]
pub use praxis_policy_builtins::secrets::vault::{
    KIND as VAULT_SECRET_KIND, VaultSecretProviderFactory,
    register as register_vault_secret_provider, registry_with_vault,
};
#[cfg(feature = "valkey")]
pub use praxis_policy_builtins::session::valkey::{
    KIND as VALKEY_KIND, ValkeyConfig, ValkeySessionStoreFactory,
};

// =============================================================================
// Builtin registration
// =============================================================================
//
// The feature list, the factory re-exports above, and the registration table
// below all describe the same set, so they belong in one crate. Split across two,
// each side needs its own umbrella feature forwarding to the other, and the two
// can disagree: an umbrella that compiles every builtin in while exporting none
// of their types still builds.

/// Generate [`register_builtin_plugins`] from a feature to factory table. Each
/// entry expands to a `#[cfg(feature = ...)]`-gated, **explicit**
/// `register_factory(KIND, Box::new(Factory))` call keyed off the builtin
/// crate's own `KIND` const.
///
/// Explicit calls (rather than `inventory` / `linkme` link-section registration)
/// are deliberate: when this engine is linked into an FFI staticlib the linker
/// garbage-collects
/// sections nothing references, which would silently drop auto-registered
/// plugins. Naming each factory here keeps its object code alive.
#[cfg(feature = "_builtin")]
macro_rules! register_builtins {
    ( $( feature $feat:literal => $krate:ident :: $factory:ident ),* $(,)? ) => {
        /// Register every enabled by-kind plugin factory on `mgr`: identity
        /// (`jwt`), delegators (`oauth`), and elicitation approvers
        /// (`elicitation-ciba`). Call before loading a config so the engine can
        /// instantiate plugins whose YAML `kind:` matches.
        ///
        /// A host adds its own with [`PolicyEngine::register_factory`], after
        /// this call so a host registration wins on a shared `kind`.
        ///
        /// PDP and session-store factories are wired through [`AplOptions`]
        /// instead; see [`builtin_pdp_factories`] and
        /// [`builtin_session_store_factories`], or use [`install_builtins`].
        #[allow(unused_variables)]
        pub fn register_builtin_plugins(mgr: &std::sync::Arc<PolicyEngine>) {
            $(
                #[cfg(feature = $feat)]
                mgr.register_factory($krate::KIND, Box::new($krate::$factory));
            )*
        }
    };
}

// Module aliases for the `register_builtins!` arms below. The macro matches a
// single identifier and uses it for both `KIND` and the factory type, which a
// multi-segment module path cannot satisfy; aliasing keeps the registration
// keyed off each extension's own `KIND` const.
#[cfg(feature = "oauth")]
use praxis_policy_builtins::plugins::delegator_oauth as oauth_builtin;
#[cfg(feature = "delegator-vault")]
use praxis_policy_builtins::plugins::delegator_vault as vault_delegator_builtin;
#[cfg(feature = "elicitation-ciba")]
use praxis_policy_builtins::plugins::elicitation_ciba as ciba_builtin;
#[cfg(feature = "api-key")]
use praxis_policy_builtins::plugins::identity_api_key as api_key_builtin;
#[cfg(feature = "jwt")]
use praxis_policy_builtins::plugins::identity_jwt as jwt_builtin;
#[cfg(feature = "experimental-quota")]
use praxis_policy_builtins::plugins::quota as quota_builtin;

#[cfg(feature = "_builtin")]
register_builtins! {
    feature "jwt"                => jwt_builtin::JwtIdentityFactory,
    feature "api-key"            => api_key_builtin::ApiKeyIdentityFactory,
    feature "oauth"              => oauth_builtin::OAuthDelegatorFactory,
    feature "delegator-vault"    => vault_delegator_builtin::VaultDelegatorFactory,
    feature "elicitation-ciba"   => ciba_builtin::CibaApproverFactory,
    // Experimental: registers only when `experimental-quota` is named, never via `builtins`.
    feature "experimental-quota" => quota_builtin::QuotaFactory,
}

/// The enabled PDP factories, ready to drop into
/// [`AplOptions::pdp_factories`]. A route's `cedar:`, `cel:` or `opa:` step
/// selects which one runs.
// `vec![]` can't replace the conditional pushes: each element is
// `#[cfg]`-gated on its feature, so the set is built incrementally.
#[cfg(feature = "_builtin")]
#[allow(unused_mut, clippy::vec_init_then_push)]
pub fn builtin_pdp_factories() -> Vec<std::sync::Arc<dyn PdpFactory>> {
    let mut factories: Vec<std::sync::Arc<dyn PdpFactory>> = Vec::new();
    #[cfg(feature = "cedar")]
    factories.push(std::sync::Arc::new(CedarDirectPdpFactory::new()));
    #[cfg(feature = "cel")]
    factories.push(std::sync::Arc::new(CelPdpFactory::new()));
    #[cfg(feature = "opa")]
    factories.push(std::sync::Arc::new(OpaPdpFactory::new()));
    factories
}

/// The enabled session-store factories, ready to drop into
/// [`AplOptions::session_store_factories`]. A `global.session_store:
/// { kind: ... }` config block selects one; absent that, the in-process
/// [`MemorySessionStore`] default stays active.
#[cfg(feature = "_builtin")]
#[allow(unused_mut, clippy::vec_init_then_push)]
pub fn builtin_session_store_factories() -> Vec<std::sync::Arc<dyn SessionStoreFactory>> {
    let mut factories: Vec<std::sync::Arc<dyn SessionStoreFactory>> = Vec::new();
    #[cfg(feature = "valkey")]
    factories.push(std::sync::Arc::new(ValkeySessionStoreFactory::new()));
    factories
}

/// Register every enabled plugin factory and install the APL config visitor on
/// `mgr` with in-process defaults (a [`MemorySessionStore`] and the default
/// baseline capabilities). The enabled PDP and session-store factories are wired
/// in, so a later config load can reference any of them by `kind`.
///
/// Secret backends are not registered here. `env` and `file` live on
/// `SecretProviderRegistry::with_builtin_backends`. Vault (`kind: vault`)
/// is compiled with the `secrets-vault` feature but still needs
/// `register_vault_secret_provider` with a host `HttpTransport`.
///
/// This is the one-call path; reach for [`register_builtin_plugins`] and
/// [`AplOptions`] directly when you need to customize capabilities or the
/// default store.
#[cfg(feature = "_builtin")]
pub fn install_builtins(mgr: &std::sync::Arc<PolicyEngine>) {
    register_builtin_plugins(mgr);

    let mut opts = AplOptions::in_process();
    opts.pdp_factories = builtin_pdp_factories();
    opts.session_store_factories = builtin_session_store_factories();

    let _visitor = register_apl(mgr, opts);
}

/// Warn that experimental extensions are compiled in. Gated on `experimental`,
/// which every `experimental-*` feature sets; call at host startup.
#[cfg(feature = "experimental")]
pub fn warn_experimental_features() {
    tracing::warn!("experimental features are enabled that should not be used in production");
}

/// A default `HttpTransport` on hyper, for hosts that inject none.
///
/// Available with the `http-hyper` feature.
#[cfg(feature = "http-hyper")]
pub mod http_hyper;

#[cfg(feature = "http-hyper")]
pub use http_hyper::HyperTransport;

/// Install the bundled hyper transport so plugins can perform outbound
/// HTTP.
///
/// PPE performs no HTTP itself, so without a transport a plugin that
/// needs one — a JWKS fetch, a token exchange — fails at initialization
/// with a message saying so. A host embedding PPE in a process that
/// already has an HTTP stack should install *that* instead, via
/// [`PolicyEngine::set_http_transport`], so the process keeps one
/// connection pool and one egress path.
///
/// Deliberately not folded into [`install_builtins`]. A host calling
/// `install_builtins` should not acquire a second HTTP stack because
/// some unrelated crate in its dependency graph happened to turn this
/// feature on. Wiring an egress path is worth one explicit line.
///
/// The transport builds its pool on first use, so calling this from a
/// short-lived initialization runtime is safe.
///
/// Destinations in the shared address table — loopback, RFC 1918,
/// link-local (including cloud metadata), CGNAT — are refused as
/// [`praxis_policy_core::http::HttpTransportError::Rejected`], including
/// a hostname that resolves only to those addresses. A local `IdP` or
/// in-cluster Vault needs
/// [`HyperTransport::with_allow_private_destinations`] installed via
/// [`PolicyEngine::set_http_transport`] instead of this helper.
///
/// Returns `false` if a transport was already installed, in which case
/// the existing one is kept.
#[cfg(feature = "http-hyper")]
pub fn install_default_http_transport(mgr: &std::sync::Arc<PolicyEngine>) -> bool {
    mgr.set_http_transport(std::sync::Arc::new(http_hyper::HyperTransport::new()))
}

/// Register the enabled builtins and use hyper when the host has not already
/// installed an HTTP transport.
///
/// Call [`PolicyEngine::set_http_transport`] first when the host has its own
/// transport. This helper keeps that transport and returns `false`; otherwise
/// it installs the bundled hyper transport and returns `true`. The bundled
/// transport refuses private destinations by default, so an in-cluster
/// Limitador needs a host transport configured to permit that destination.
#[cfg(all(feature = "_builtin", feature = "http-hyper"))]
pub fn install_builtins_with_default_http_transport(mgr: &std::sync::Arc<PolicyEngine>) -> bool {
    let installed = install_default_http_transport(mgr);
    install_builtins(mgr);
    installed
}

#[cfg(all(test, feature = "_builtin"))]
mod tests {
    use super::*;
    use std::sync::Arc;

    #[test]
    fn install_builtins_runs_without_panic() {
        let mgr = Arc::new(PolicyEngine::default());
        install_builtins(&mgr);
    }

    #[cfg(feature = "http-hyper")]
    #[test]
    fn combined_bootstrap_installs_hyper_only_without_an_injected_transport() {
        let standalone = Arc::new(PolicyEngine::default());
        assert!(install_builtins_with_default_http_transport(&standalone));

        let embedded = Arc::new(PolicyEngine::default());
        assert!(embedded.set_http_transport(Arc::new(
            HyperTransport::new().with_allow_private_destinations()
        )));
        assert!(!install_builtins_with_default_http_transport(&embedded));
    }

    #[test]
    fn pdp_factories_track_enabled_features() {
        let expected = usize::from(cfg!(feature = "cedar"))
            + usize::from(cfg!(feature = "cel"))
            + usize::from(cfg!(feature = "opa"));
        assert_eq!(
            builtin_pdp_factories().len(),
            expected,
            "one PDP factory per enabled feature",
        );
    }

    #[test]
    fn every_builtin_pdp_kind_is_in_the_differential_harness() {
        // Source of truth is the harness crate, not a local copy. A new
        // factory in `builtin_pdp_factories` that is not on that list means
        // the dialect was added to the router/facade without the differential
        // harness — which is what issue #25 forbids.
        use praxis_policy_pdp_diff::HARNESS_PDP_KINDS;
        for factory in builtin_pdp_factories() {
            assert!(
                HARNESS_PDP_KINDS.contains(&factory.kind()),
                "kind '{}' is registered in builtin_pdp_factories but not in \
                 the ppe-pdp-diff harness. Add a Dialect arm and catalog \
                 coverage there; registering it on PdpRouter is not enough.",
                factory.kind()
            );
        }
    }

    #[test]
    fn session_store_factories_track_enabled_features() {
        let expected = usize::from(cfg!(feature = "valkey"));
        assert_eq!(
            builtin_session_store_factories().len(),
            expected,
            "one session-store factory per enabled feature",
        );
    }

    /// Load a one-plugin config against a engine with the builtins installed,
    /// and return the error text (empty string on success).
    ///
    /// Goes through `load_config_yaml` rather than inspecting the registry
    /// because that is the path an operator hits: the question is whether their
    /// YAML `kind:` resolves, not what the map contains.
    fn load_error_for_kind(kind: &str) -> String {
        let mgr = Arc::new(PolicyEngine::default());
        install_builtins(&mgr);
        let yaml =
            format!("plugins:\n  - name: probe\n    kind: {kind}\n    hooks: [identity.resolve]\n");
        match mgr.load_config_yaml(&yaml) {
            Ok(()) => String::new(),
            Err(e) => format!("{e}"),
        }
    }

    /// The by-kind plugin table had no test, unlike the PDP and session-store
    /// lists. So a builtin could leave the umbrella, or quietly rejoin it, with
    /// nothing failing. This pins the set.
    ///
    /// Each enabled builtin must resolve its `kind`. The probe config is
    /// deliberately minimal, so most of these still fail on their own settings —
    /// what matters is that they fail on settings rather than on a missing
    /// factory, which is a different message and a different operator problem.
    #[test]
    fn every_enabled_builtin_resolves_its_kind() {
        let expected = [
            (cfg!(feature = "jwt"), "identity/jwt"),
            (cfg!(feature = "api-key"), "identity/api-key"),
            (cfg!(feature = "oauth"), "delegator/oauth"),
            (cfg!(feature = "delegator-vault"), "delegator/vault"),
            (cfg!(feature = "elicitation-ciba"), "elicitation/ciba"),
        ];
        for (enabled, kind) in expected {
            if !enabled {
                continue;
            }
            let err = load_error_for_kind(kind);
            assert!(
                !err.contains("no factory registered"),
                "{kind} is enabled, so its factory must be registered; got: {err}"
            );
        }
    }

    /// The PII scanner and audit logger are reference implementations now, so the
    /// umbrella must not register them. A host supplies them instead.
    ///
    /// Asserted as the exact operator-visible failure, because that message is
    /// what tells someone their config needs a host registration rather than a
    /// different feature flag.
    #[test]
    fn the_reference_plugins_are_not_registered_by_the_umbrella() {
        for kind in ["validator/pii-scan", "audit/logger"] {
            let err = load_error_for_kind(kind);
            assert!(
                err.contains("no factory registered"),
                "{kind} must not be bundled; got: {err}"
            );
            assert!(
                err.contains(kind),
                "the error must name the unresolved kind: {err}"
            );
        }
    }

    /// quota is experimental: `builtins` alone must not register it.
    #[cfg(not(feature = "experimental-quota"))]
    #[test]
    fn quota_is_not_registered_without_the_experimental_feature() {
        let err = load_error_for_kind("quota/limitador");
        assert!(
            err.contains("no factory registered"),
            "quota must not register without experimental-quota; got: {err}"
        );
    }

    /// With `experimental-quota` named, `install_builtins` registers quota (it
    /// then fails on config, not on a missing factory).
    #[cfg(feature = "experimental-quota")]
    #[test]
    fn quota_registers_with_the_experimental_feature() {
        let err = load_error_for_kind("quota/limitador");
        assert!(
            !err.contains("no factory registered"),
            "experimental-quota is on, so quota must register; got: {err}"
        );
    }
}