treetop_core/

engine.rs

use cedar_policy::{
    Authorizer, Entities, Entity, Policy, PolicyId, PolicySet, Request as CedarRequest, Schema,
};
use std::collections::{HashMap, HashSet};
use std::sync::{Arc, OnceLock};
use std::time::{Duration, Instant, SystemTime};
use std::vec;

use crate::labels::LabelRegistry;
use crate::policy_match::{
    action_match_reason, matches_effect, principal_match_reason, resource_match_reason,
};
use crate::query::{ActionQuery, PrincipalQuery, ResourceQuery};
use crate::timers::PhaseTimer;
use crate::traits::CedarAtom;
use crate::types::{
    Decision, DecisionDiagnostics, FromDecisionWithPolicy, PermitPolicies, PermitPolicy,
    PolicyEffectFilter, PolicyMatchReason, PolicyVersion, Request, RequestContext, Resource,
    UserPolicies,
};
use crate::{Groups, Principal};
use crate::{error::PolicyError, loader};
use arc_swap::ArcSwap;

use sha2::{Digest, Sha256};
use tracing::debug;
#[cfg(feature = "observability")]
use tracing::info_span;

#[cfg(feature = "observability")]
use crate::metrics::{
    EvaluationObservation, EvaluationPhases, MatchedPolicySource, get_sink, metrics_enabled,
    record_evaluation_observation, record_reload,
};

/// Static cached Authorizer instance (stateless, reusable across evaluations).
fn get_authorizer() -> &'static Authorizer {
    static AUTHORIZER: OnceLock<Authorizer> = OnceLock::new();
    AUTHORIZER.get_or_init(Authorizer::new)
}

/// Aggregates timing information for all evaluation phases.
#[derive(Debug)]
struct EvalTimers {
    /// Total elapsed time from start of evaluation
    total_start: Option<Instant>,
    /// Whether individual phase timers should sample the clock.
    measure_enabled: bool,
    /// Whether debug tracing was enabled when evaluation started.
    debug_enabled: bool,
    /// Time spent applying labels
    labels: Duration,
    /// Time spent constructing Cedar request
    construct_req: Duration,
    /// Time spent building Cedar entities
    entities: Duration,
    /// Time spent resolving groups
    groups: Duration,
    /// Time spent performing authorization
    authz: Duration,
}

impl EvalTimers {
    fn start(measure_enabled: bool, debug_enabled: bool) -> Self {
        Self {
            total_start: measure_enabled.then(Instant::now),
            measure_enabled,
            debug_enabled,
            labels: Duration::ZERO,
            construct_req: Duration::ZERO,
            entities: Duration::ZERO,
            groups: Duration::ZERO,
            authz: Duration::ZERO,
        }
    }

    fn total_elapsed(&self) -> Duration {
        self.total_start
            .map_or(Duration::ZERO, |start| start.elapsed())
    }
}

/// Result of preparing a request for authorization: Cedar request, entities, snapshot, and phase timings.
struct PreparedRequest {
    cedar_req: CedarRequest,
    entities: Entities,
    snapshot: Snapshot,
    timers: EvalTimers,
    #[cfg(feature = "observability")]
    sink: crate::metrics::SinkGuard,
    #[cfg(feature = "observability")]
    metrics_enabled: bool,
}

/// Immutable snapshot of a compiled policy set, along with metadata.
#[derive(Debug)]
struct PolicySnapshot {
    set: PolicySet,
    version: PolicyVersion,
    permit_policies: HashMap<PolicyId, PermitPolicy>,
    forbid_policy_ids: HashMap<PolicyId, String>,
    schema: Option<Arc<Schema>>,
}

/// Convenience alias for a shared policy snapshot.
type Snapshot = Arc<PolicySnapshot>;

impl PolicySnapshot {
    fn from_policy_text(policy_text: &str) -> Result<Self, PolicyError> {
        Self::from_policy_text_with_schema(policy_text, None)
    }

    fn from_policy_text_with_schema(
        policy_text: &str,
        schema: Option<Arc<Schema>>,
    ) -> Result<Self, PolicyError> {
        let set = match schema.as_deref() {
            Some(schema) => loader::compile_policy_with_schema(policy_text, schema)?,
            None => loader::compile_policy(policy_text)?,
        };
        let permit_policies = loader::precompute_permit_policies(&set)?;
        let forbid_policy_ids = loader::precompute_forbid_policy_ids(&set);

        let mut hasher = Sha256::new();
        hasher.update(policy_text.as_bytes());
        let digest = hasher.finalize();
        let mut hash = String::with_capacity(digest.len() * 2);
        const HEX: &[u8; 16] = b"0123456789abcdef";
        for byte in digest {
            hash.push(char::from(HEX[usize::from(byte >> 4)]));
            hash.push(char::from(HEX[usize::from(byte & 0x0f)]));
        }

        Ok(PolicySnapshot {
            set,
            version: PolicyVersion {
                hash: hash.into(),
                loaded_at: humantime::format_rfc3339(SystemTime::now())
                    .to_string()
                    .into(),
            },
            permit_policies,
            forbid_policy_ids,
            schema,
        })
    }

    fn policy_set(&self) -> &PolicySet {
        &self.set
    }

    fn version(&self) -> PolicyVersion {
        self.version.clone()
    }

    fn schema(&self) -> Option<&Schema> {
        self.schema.as_deref()
    }
}

/// Extract all permit policies from the Cedar authorization result.
#[inline]
fn extract_permit_policies(
    snapshot: &PolicySnapshot,
    result: &cedar_policy::Response,
) -> PermitPolicies {
    if result.decision() != cedar_policy::Decision::Allow {
        return PermitPolicies::empty();
    }

    result
        .diagnostics()
        .reason()
        .filter_map(|reason| snapshot.permit_policies.get(reason))
        .cloned()
        .collect()
}

/// Extract matched forbid policy IDs from a Cedar authorization result.
#[inline]
fn extract_forbid_policy_ids(
    snapshot: &PolicySnapshot,
    result: &cedar_policy::Response,
) -> Vec<String> {
    if result.decision() != cedar_policy::Decision::Deny {
        return Vec::new();
    }

    let mut ids: Vec<String> = result
        .diagnostics()
        .reason()
        .filter_map(|reason| snapshot.forbid_policy_ids.get(reason).cloned())
        .collect();
    ids.sort();
    ids.dedup();
    ids
}

/// Iterate over groups from a request principal.
#[inline]
fn request_groups(request: &Request) -> Option<&Groups> {
    match &request.principal {
        Principal::User(user) => Some(user.groups()),
        Principal::Group(_) => None,
    }
}

/// Apply label augmentations to a resource.
#[inline]
fn apply_labels(
    registry: &LabelRegistry,
    resource: &crate::types::Resource,
    timers: &mut EvalTimers,
) -> Option<crate::types::Resource> {
    let measure_enabled = timers.measure_enabled;
    let _timer = PhaseTimer::new_if(&mut timers.labels, measure_enabled);
    #[cfg(feature = "observability")]
    let _label_span = info_span!("apply_labels").entered();
    registry.apply_to_clone_if_applicable(resource)
}

/// Build the Cedar request context from the optional typed context.
#[inline]
fn build_effective_context(
    request_context: Option<&RequestContext>,
) -> Result<cedar_policy::Context, PolicyError> {
    match request_context {
        Some(context) if !context.is_empty() => context.to_cedar_context(),
        _ => Ok(cedar_policy::Context::empty()),
    }
}

/// Build a Cedar request from the authorization request and resource.
/// UIDs should be pre-converted to avoid redundant conversions.
#[inline]
fn build_cedar_req(
    principal_uid: cedar_policy::EntityUid,
    action_uid: cedar_policy::EntityUid,
    resource_uid: cedar_policy::EntityUid,
    context: cedar_policy::Context,
    schema: Option<&Schema>,
    timers: &mut EvalTimers,
) -> Result<CedarRequest, PolicyError> {
    let measure_enabled = timers.measure_enabled;
    let _timer = PhaseTimer::new_if(&mut timers.construct_req, measure_enabled);
    #[cfg(feature = "observability")]
    let _req_span = info_span!("construct_cedar_req").entered();

    Ok(CedarRequest::new(
        principal_uid,
        action_uid,
        resource_uid,
        context,
        schema,
    )?)
}

/// Build Cedar entities for the principal, resource, and groups.
/// UIDs should be pre-converted to avoid redundant conversions.
#[inline]
fn build_entities(
    principal_uid: cedar_policy::EntityUid,
    resource_uid: cedar_policy::EntityUid,
    resource: &crate::types::Resource,
    groups: Option<&Groups>,
    schema: Option<&Schema>,
    timers: &mut EvalTimers,
) -> Result<Entities, PolicyError> {
    let group_uids = {
        let measure_enabled = timers.measure_enabled;
        let _timer = PhaseTimer::new_if(&mut timers.groups, measure_enabled);
        #[cfg(feature = "observability")]
        let _groups_span = info_span!("resolve_groups").entered();

        let mut group_uids = HashSet::with_capacity(groups.map_or(0, Groups::len));
        if let Some(groups) = groups {
            for group in groups {
                group_uids.insert(group.cedar_entity_uid()?);
            }
        }
        group_uids
    };

    // Group resolution is deliberately measured outside this phase so phase
    // totals are non-overlapping.
    let entities = {
        let measure_enabled = timers.measure_enabled;
        let _timer = PhaseTimer::new_if(&mut timers.entities, measure_enabled);
        #[cfg(feature = "observability")]
        let _entity_span = info_span!("construct_entities").entered();

        // Construct resource entity
        let resource_attrs = resource.cedar_attr()?;
        let resource_entity =
            cedar_policy::Entity::new(resource_uid, resource_attrs, Default::default())?;

        // Construct group entities before moving the parent set into the
        // principal. This avoids cloning the complete HashSet allocation.
        let mut all_entities = Vec::with_capacity(group_uids.len() + 2);
        all_entities.extend(group_uids.iter().cloned().map(Entity::with_uid));

        // Construct principal entity with groups as parents, then batch all
        // entities into a single call. Entity order has no Cedar semantics.
        let principal_entity = Entity::new(principal_uid, HashMap::new(), group_uids)?;
        all_entities.push(principal_entity);
        all_entities.push(resource_entity);

        // Combine all entities in a single call to reduce overhead
        Entities::empty().add_entities(all_entities, schema)?
    };

    if timers.debug_enabled {
        debug!(
            event = "Request",
            phase = "Entities",
            time = timers.entities.as_micros(),
            entity_count = entities.iter().count()
        );
    }

    Ok(entities)
}

/// The main engine handle. Thread-safe and cheaply cloneable.
///
/// Cloning is cheap (just increments Arc refcounts), but for multithreaded
/// applications, wrapping in `Arc<PolicyEngine>` and using `Arc::clone()`
/// is more idiomatic and makes ownership clearer.
///
/// For single-threaded use or when passing the engine to a single thread,
/// you can simply clone it directly.
#[derive(Clone)]
pub struct PolicyEngine {
    /// Shared pointer to an `ArcSwap` holding the current policy snapshot.
    inner: Arc<ArcSwap<PolicySnapshot>>,
    /// Optional label registry for augmenting resources with derived attributes.
    label_registry: Option<Arc<LabelRegistry>>,
}

impl From<PolicyEngine> for PolicyVersion {
    fn from(engine: PolicyEngine) -> Self {
        engine.current_version()
    }
}

impl From<&PolicyEngine> for PolicyVersion {
    fn from(engine: &PolicyEngine) -> Self {
        engine.current_version()
    }
}

impl PolicyEngine {
    pub fn new_from_str(policy_text: &str) -> Result<Self, PolicyError> {
        let snapshot: Snapshot = Arc::new(PolicySnapshot::from_policy_text(policy_text)?);
        Ok(PolicyEngine {
            inner: Arc::new(ArcSwap::from(snapshot)),
            label_registry: None,
        })
    }

    /// Create a new policy engine with schema-based policy and request validation.
    pub fn new_from_str_with_schema(
        policy_text: &str,
        schema: Schema,
    ) -> Result<Self, PolicyError> {
        let snapshot: Snapshot = Arc::new(PolicySnapshot::from_policy_text_with_schema(
            policy_text,
            Some(Arc::new(schema)),
        )?);
        Ok(PolicyEngine {
            inner: Arc::new(ArcSwap::from(snapshot)),
            label_registry: None,
        })
    }

    /// Create a new policy engine from policy text and Cedar schema text.
    pub fn new_from_str_with_cedarschema(
        policy_text: &str,
        schema_text: &str,
    ) -> Result<Self, PolicyError> {
        let schema: Schema = schema_text
            .parse()
            .map_err(|e| PolicyError::ParseError(format!("failed to parse Cedar schema: {e}")))?;
        Self::new_from_str_with_schema(policy_text, schema)
    }

    /// Create a new policy engine with a label registry.
    ///
    /// This is a convenience method that combines `new_from_str` and `with_label_registry`.
    pub fn with_label_registry(mut self, registry: LabelRegistry) -> Self {
        self.label_registry = Some(Arc::new(registry));
        self
    }

    /// Set or replace the label registry for this engine.
    ///
    /// This allows updating the labelers after the engine has been created.
    pub fn set_label_registry(&mut self, registry: LabelRegistry) {
        self.label_registry = Some(Arc::new(registry));
    }

    /// Get a reference to the label registry, if one is configured.
    pub fn label_registry(&self) -> Option<&LabelRegistry> {
        self.label_registry.as_deref()
    }

    pub fn reload_from_str(&self, policy_text: &str) -> Result<(), PolicyError> {
        let current_snapshot = self.current_snapshot();
        let had_schema = current_snapshot.schema.is_some();
        let schema = current_snapshot.schema.clone();
        let new_snapshot: Snapshot = Arc::new(PolicySnapshot::from_policy_text_with_schema(
            policy_text,
            schema,
        )?);
        self.inner.store(new_snapshot);
        debug!(
            event = "PolicyReload",
            schema_enabled = had_schema,
            schema_reloaded = false
        );
        // Track reloads for metrics (no-op if feature disabled or no sink configured)
        #[cfg(feature = "observability")]
        record_reload();
        Ok(())
    }

    /// Reload policies and replace the engine schema at the same time.
    pub fn reload_from_str_with_schema(
        &self,
        policy_text: &str,
        schema: Schema,
    ) -> Result<(), PolicyError> {
        let had_schema = self.current_snapshot().schema.is_some();
        let new_snapshot: Snapshot = Arc::new(PolicySnapshot::from_policy_text_with_schema(
            policy_text,
            Some(Arc::new(schema)),
        )?);
        self.inner.store(new_snapshot);
        debug!(
            event = "PolicyReload",
            schema_enabled = true,
            schema_reloaded = true,
            schema_previously_enabled = had_schema
        );
        // Track reloads for metrics (no-op if feature disabled or no sink configured)
        #[cfg(feature = "observability")]
        record_reload();
        Ok(())
    }

    /// Reload policies and replace the engine schema from Cedar schema text.
    pub fn reload_from_str_with_cedarschema(
        &self,
        policy_text: &str,
        schema_text: &str,
    ) -> Result<(), PolicyError> {
        let schema: Schema = schema_text
            .parse()
            .map_err(|e| PolicyError::ParseError(format!("failed to parse Cedar schema: {e}")))?;
        self.reload_from_str_with_schema(policy_text, schema)
    }

    /// Get the current immutable snapshot.
    fn current_snapshot(&self) -> Snapshot {
        self.inner.load_full()
    }

    /// Get the current policy version.
    ///
    /// The `hash` is computed from the policy text, and `loaded_at` reflects
    /// when this snapshot was installed.
    pub fn current_version(&self) -> PolicyVersion {
        self.current_snapshot().version()
    }

    /// Prepare a request for authorization: accumulate labels, build Cedar entities, resolve groups.
    ///
    /// This separates request preparation from the authorization decision, making both
    /// more testable and the main hot path more readable.
    fn prepare(
        &self,
        request: &Request,
        request_context: Option<&RequestContext>,
    ) -> Result<PreparedRequest, PolicyError> {
        let snapshot = self.current_snapshot();
        let schema = snapshot.schema();
        #[cfg(feature = "observability")]
        let sink = get_sink();
        #[cfg(feature = "observability")]
        let metrics_enabled = metrics_enabled(&sink);
        #[cfg(not(feature = "observability"))]
        let metrics_enabled = false;
        let debug_enabled = tracing::enabled!(tracing::Level::DEBUG);
        let mut timers = EvalTimers::start(debug_enabled || metrics_enabled, debug_enabled);

        let groups = request_groups(request);

        if timers.debug_enabled {
            debug!(
                event = "Request",
                phase = "Evaluation",
                group_count = groups.map_or(0, Groups::len)
            );
        }

        // Convert each UID once after trusted label derivation is complete.
        let principal_uid = request.principal.cedar_entity_uid()?;
        let action_uid = request.action.cedar_entity_uid()?;

        let labelled_resource = if let Some(registry) = &self.label_registry {
            let labelled_resource = apply_labels(registry, &request.resource, &mut timers);
            if timers.debug_enabled {
                let resource_for_metrics = labelled_resource.as_ref().unwrap_or(&request.resource);
                debug!(
                    event = "Request",
                    phase = "LabelsApplied",
                    time = timers.labels.as_micros(),
                    attribute_count = resource_for_metrics.attributes().len()
                );
            }
            labelled_resource
        } else {
            if timers.debug_enabled {
                debug!(
                    event = "Request",
                    phase = "LabelsApplied",
                    time = timers.labels.as_micros()
                );
            }
            None
        };
        let resource_for_entities = labelled_resource.as_ref().unwrap_or(&request.resource);
        let resource_uid = resource_for_entities.cedar_entity_uid()?;
        let context = build_effective_context(request_context)?;

        if timers.debug_enabled {
            debug!(
                event = "Request",
                phase = "Parsed",
                group_count = groups.map_or(0, Groups::len),
                attribute_count = resource_for_entities.attributes().len(),
                request_context_attribute_count = request_context.map_or(0, RequestContext::len)
            );
        }

        // The request and entity graph both own the same principal and resource
        // IDs. Clone each UID once, then move both copies into Cedar instead of
        // cloning again inside both builders.
        let principal_uid_for_entities = principal_uid.clone();
        let resource_uid_for_entities = resource_uid.clone();

        // Build Cedar request with pre-converted UIDs
        let cedar_req = build_cedar_req(
            principal_uid,
            action_uid,
            resource_uid,
            context,
            schema,
            &mut timers,
        )?;

        // Build entities with pre-converted UIDs and potentially-modified resource
        let entities = build_entities(
            principal_uid_for_entities,
            resource_uid_for_entities,
            resource_for_entities,
            groups,
            schema,
            &mut timers,
        )?;

        if timers.debug_enabled {
            debug!(
                event = "Request",
                phase = "GroupsResolved",
                time = timers.groups.as_micros(),
            );
        }

        Ok(PreparedRequest {
            cedar_req,
            entities,
            snapshot,
            timers,
            #[cfg(feature = "observability")]
            sink,
            #[cfg(feature = "observability")]
            metrics_enabled,
        })
    }

    /// Evaluate a policy request against the currently loaded policy set.
    ///
    /// This method performs a complete Cedar policy evaluation:
    /// 1. Applies any registered labelers to augment resource attributes
    /// 2. Constructs Cedar entities for the principal (including groups), action, and resource
    /// 3. Executes the Cedar authorization decision
    /// 4. Returns either `Allow` (with the matching policy) or `Deny`, both including version metadata
    ///
    /// # Arguments
    ///
    /// * `request` - The authorization request containing the principal, action, and resource
    ///
    /// # Returns
    ///
    /// * `Ok(Decision::Allow)` - If at least one permit policy matches and no forbid policies match
    /// * `Ok(Decision::Deny)` - If no permit policies match or if a forbid policy matches
    /// * `Err(PolicyError)` - If there's an error constructing entities, parsing the request, or during evaluation
    ///
    /// # Examples
    ///
    /// ```rust
    /// use treetop_core::{PolicyEngine, Request, Principal, User, Action, Resource, Decision};
    ///
    /// let policies = r#"
    ///     permit (
    ///         principal == User::"alice",
    ///         action == Action::"read",
    ///         resource == Document::"doc1"
    ///     );
    /// "#;
    ///
    /// let engine = PolicyEngine::new_from_str(policies).unwrap();
    ///
    /// let request = Request {
    ///     principal: Principal::User(User::new("alice", None, None)),
    ///     action: Action::new("read", None),
    ///     resource: Resource::new("Document", "doc1"),
    /// };
    ///
    /// let decision = engine.evaluate(&request).unwrap();
    /// assert!(matches!(decision, Decision::Allow { .. }));
    ///
    /// // Access version information
    /// if let Decision::Allow { version, .. } = decision {
    ///     println!("Allowed by policy version: {}", version.hash);
    /// }
    /// ```
    ///
    /// # Thread Safety
    ///
    /// This method is thread-safe and lock-free. Multiple threads can evaluate requests
    /// concurrently without blocking each other.
    #[cfg_attr(
        feature = "observability",
        tracing::instrument(name = "policy_evaluation", skip_all)
    )]
    pub fn evaluate(&self, request: &Request) -> Result<Decision, PolicyError> {
        Ok(self.evaluate_internal(request, None, false)?.decision)
    }

    /// Evaluate a request with explicit Cedar request context.
    pub fn evaluate_with_context(
        &self,
        request: &Request,
        request_context: &RequestContext,
    ) -> Result<Decision, PolicyError> {
        Ok(self
            .evaluate_internal(request, Some(request_context), false)?
            .decision)
    }

    /// Evaluate a request and include deny-side forbid diagnostics.
    pub fn evaluate_with_diagnostics(
        &self,
        request: &Request,
    ) -> Result<DecisionDiagnostics, PolicyError> {
        self.evaluate_internal(request, None, true)
    }

    /// Evaluate a request with explicit context and include deny diagnostics.
    pub fn evaluate_with_context_and_diagnostics(
        &self,
        request: &Request,
        request_context: &RequestContext,
    ) -> Result<DecisionDiagnostics, PolicyError> {
        self.evaluate_internal(request, Some(request_context), true)
    }

    fn evaluate_internal(
        &self,
        request: &Request,
        request_context: Option<&RequestContext>,
        include_forbid_diagnostics: bool,
    ) -> Result<DecisionDiagnostics, PolicyError> {
        // Prepare the request: apply labels, build entities, resolve groups
        let mut prepared = self.prepare(request, request_context)?;

        // Perform authorization with RAII timing (using cached Authorizer)
        let result = {
            let measure_enabled = prepared.timers.measure_enabled;
            let _timer = PhaseTimer::new_if(&mut prepared.timers.authz, measure_enabled);
            #[cfg(feature = "observability")]
            let _authz_span = info_span!("authorize").entered();
            get_authorizer().is_authorized(
                &prepared.cedar_req,
                &prepared.snapshot.set,
                &prepared.entities,
            )
        };

        if prepared.timers.debug_enabled {
            debug!(
                event = "Request",
                phase = "Authorized",
                time = prepared.timers.authz.as_micros(),
                decision = ?result.decision(),
            );
        }

        let version = prepared.snapshot.version();
        if prepared.timers.debug_enabled {
            debug!(
                event = "Request",
                phase = "Result",
                time = prepared.timers.total_elapsed().as_micros(),
                result = ?result.decision(),
                policy_hash = %version.hash,
                policy_loaded_at = %version.loaded_at,
            );
        }

        // Permit metadata is part of Allow decisions. Forbid IDs are only
        // materialized when the caller explicitly requests diagnostics. Metrics
        // borrow matching IDs from the Cedar response and compiled snapshot.
        let permit_policies = extract_permit_policies(&prepared.snapshot, &result);
        let collect_forbid_ids = include_forbid_diagnostics;
        let forbid_policy_ids = if collect_forbid_ids {
            extract_forbid_policy_ids(&prepared.snapshot, &result)
        } else {
            Vec::new()
        };
        let decision =
            Decision::from_decision_with_policy(result.decision(), permit_policies, version)?;

        // Record metrics (no-op when no sink is configured or feature disabled)
        #[cfg(feature = "observability")]
        {
            if prepared.metrics_enabled {
                let dur = prepared.timers.total_elapsed();
                let allowed = result.decision() == cedar_policy::Decision::Allow;
                let phases = EvaluationPhases {
                    apply_labels_ms: prepared.timers.labels.as_secs_f64() * 1000.0,
                    construct_entities_ms: prepared.timers.entities.as_secs_f64() * 1000.0,
                    resolve_groups_ms: prepared.timers.groups.as_secs_f64() * 1000.0,
                    authorize_ms: prepared.timers.authz.as_secs_f64() * 1000.0,
                    total_ms: dur.as_secs_f64() * 1000.0,
                };
                let matched_policies = match &decision {
                    Decision::Allow { policies, .. } => MatchedPolicySource::Allow(policies),
                    Decision::Deny { .. } => MatchedPolicySource::Deny {
                        diagnostics: result.diagnostics(),
                        policy_ids: &prepared.snapshot.forbid_policy_ids,
                    },
                };
                let observation = EvaluationObservation::new(
                    dur,
                    allowed,
                    &request.action,
                    phases,
                    matched_policies,
                );

                record_evaluation_observation(&prepared.sink, &observation);
            }
        }

        Ok(DecisionDiagnostics {
            decision,
            matched_forbid_policy_ids: forbid_policy_ids,
        })
    }

    /// List permit-policy candidates whose scope matches a user.
    ///
    /// This mirrors [`PolicyEngine::evaluate`] input shape for principal identity:
    /// user id + groups + shared namespace.
    ///
    /// Matching includes all Cedar principal-constraint forms:
    /// - `principal == User::"..."`
    /// - `principal in Group::"..."`
    /// - `principal`
    /// - `principal is User`
    /// - `principal is User in Group::"..."`
    ///
    /// Cedar `when` and `unless` clauses are not evaluated. The result is not
    /// an authorization decision; use [`PolicyEngine::evaluate`] to authorize.
    /// Resource constraints are not applied in this method. To additionally
    /// filter by policy resource constraints, use
    /// [`PolicyEngine::list_policies_for_user_with_resource`].
    ///
    /// Output is deterministic: policies are sorted by Cedar policy ID.
    /// Each returned policy includes match reasons via `UserPolicies::matches()`.
    ///
    /// # Arguments
    ///
    /// * `user` - User ID
    /// * `groups` - Group IDs the user belongs to
    /// * `namespace` - Optional shared namespace path for both user and groups
    ///
    /// # Returns
    ///
    /// * `Ok(UserPolicies)` - Matching policies and match metadata
    /// * `Err(PolicyError)` - If entity UID construction fails
    ///
    /// # Examples
    ///
    /// ```rust
    /// use treetop_core::PolicyEngine;
    ///
    /// let policies = r#"
    ///     permit (principal == User::"alice", action, resource);
    ///     permit (principal in Group::"admins", action, resource);
    /// "#;
    ///
    /// let engine = PolicyEngine::new_from_str(policies).unwrap();
    /// let user_policies = engine.list_policies_for_user("alice", &["admins"], &[]).unwrap();
    ///
    /// assert_eq!(user_policies.policies().len(), 2);
    /// assert!(!user_policies.matches().is_empty());
    /// ```
    pub fn list_policies_for_user(
        &self,
        user: &str,
        groups: &[&str],
        namespace: &[&str],
    ) -> Result<UserPolicies, PolicyError> {
        self.list_policies_for_user_with_resource_and_effect(
            user,
            groups,
            namespace,
            None,
            PolicyEffectFilter::Permit,
        )
    }

    /// List permit-policy candidates whose scope matches a concrete request.
    ///
    /// This mirrors [`PolicyEngine::evaluate`] by accepting `&Request` and uses:
    /// - the request principal (including user group membership, if any)
    /// - the request action
    /// - the request resource
    ///
    /// Cedar `when` and `unless` clauses are not evaluated. The result is not
    /// an authorization decision. This method defaults to permit policies; use
    /// [`PolicyEngine::list_policies_with_effect`] for an explicit effect.
    pub fn list_policies(&self, request: &Request) -> Result<UserPolicies, PolicyError> {
        self.list_policies_with_effect(request, PolicyEffectFilter::Permit)
    }

    /// List policy candidates for a request, with explicit effect filtering.
    ///
    /// Cedar `when` and `unless` clauses are not evaluated.
    pub fn list_policies_with_effect(
        &self,
        request: &Request,
        effect_filter: PolicyEffectFilter,
    ) -> Result<UserPolicies, PolicyError> {
        let principal = PrincipalQuery::from_principal(&request.principal)?;
        let action = ActionQuery::from_action(&request.action)?;
        self.list_policies_dispatch(
            &request.principal.to_string(),
            &principal,
            Some(&action),
            Some(&request.resource),
            effect_filter,
        )
    }

    /// List all policies applicable to a user, optionally filtering by resource constraints.
    ///
    /// This variant applies both principal and resource constraints:
    /// - principal constraints as described in [`PolicyEngine::list_policies_for_user`]
    /// - resource constraints (`==`, `in`, `is`, `is in`, `any`) when `resource` is provided
    ///
    /// When `resource` is `None`, behavior is equivalent to
    /// [`PolicyEngine::list_policies_for_user`].
    ///
    /// Returned `UserPolicies` includes match reasons for principal and, when
    /// applicable, resource matches.
    pub fn list_policies_for_user_with_resource(
        &self,
        user: &str,
        groups: &[&str],
        namespace: &[&str],
        resource: Option<&Resource>,
    ) -> Result<UserPolicies, PolicyError> {
        self.list_policies_for_user_with_resource_and_effect(
            user,
            groups,
            namespace,
            resource,
            PolicyEffectFilter::Permit,
        )
    }

    /// List all policies applicable to a user with optional resource and effect filtering.
    pub fn list_policies_for_user_with_resource_and_effect(
        &self,
        user: &str,
        groups: &[&str],
        namespace: &[&str],
        resource: Option<&Resource>,
        effect_filter: PolicyEffectFilter,
    ) -> Result<UserPolicies, PolicyError> {
        let principal = PrincipalQuery::for_user(user, groups, namespace)?;
        self.list_policies_dispatch(user, &principal, None, resource, effect_filter)
    }

    /// List all policies applicable to a group principal.
    ///
    /// Useful when callers model group identities directly as principals
    /// (mirroring `Principal::Group` in [`PolicyEngine::evaluate`]).
    ///
    /// Resource constraints are not applied in this method. To also filter by
    /// resource constraints, use
    /// [`PolicyEngine::list_policies_for_group_with_resource`].
    pub fn list_policies_for_group(
        &self,
        group: &str,
        namespace: &[&str],
    ) -> Result<UserPolicies, PolicyError> {
        self.list_policies_for_group_with_resource_and_effect(
            group,
            namespace,
            None,
            PolicyEffectFilter::Permit,
        )
    }

    /// List all policies applicable to a group principal, optionally filtering by resource constraints.
    ///
    /// This applies principal constraints for a group principal and, when
    /// `resource` is provided, resource constraints as well.
    pub fn list_policies_for_group_with_resource(
        &self,
        group: &str,
        namespace: &[&str],
        resource: Option<&Resource>,
    ) -> Result<UserPolicies, PolicyError> {
        self.list_policies_for_group_with_resource_and_effect(
            group,
            namespace,
            resource,
            PolicyEffectFilter::Permit,
        )
    }

    /// List all policies applicable to a group principal with optional resource and effect filtering.
    pub fn list_policies_for_group_with_resource_and_effect(
        &self,
        group: &str,
        namespace: &[&str],
        resource: Option<&Resource>,
        effect_filter: PolicyEffectFilter,
    ) -> Result<UserPolicies, PolicyError> {
        let principal = PrincipalQuery::for_group(group, namespace)?;
        self.list_policies_dispatch(group, &principal, None, resource, effect_filter)
    }

    fn list_policies_dispatch(
        &self,
        principal_id: &str,
        principal: &PrincipalQuery,
        action: Option<&ActionQuery>,
        resource: Option<&Resource>,
        effect_filter: PolicyEffectFilter,
    ) -> Result<UserPolicies, PolicyError> {
        let snapshot = self.current_snapshot();
        let policies = snapshot.set.policies();
        let resource_query = match resource {
            Some(resource) => Some(ResourceQuery::from_resource(resource)?),
            None => None,
        };
        let mut matching_policies: Vec<(Policy, Vec<PolicyMatchReason>)> = Vec::new();

        for policy in policies {
            if !matches_effect(policy.effect(), effect_filter) {
                continue;
            }

            let Some(principal_reason) =
                principal_match_reason(policy.principal_constraint(), principal)
            else {
                continue;
            };

            let Some(action_reason) = action_match_reason(policy.action_constraint(), action)
            else {
                continue;
            };

            let Some(resource_reason) =
                resource_match_reason(policy.resource_constraint(), resource_query.as_ref())
            else {
                continue;
            };

            let mut reasons = vec![principal_reason];
            if let Some(action_reason) = action_reason {
                reasons.push(action_reason);
            }
            if let Some(resource_reason) = resource_reason {
                reasons.push(resource_reason);
            }

            matching_policies.push((policy.clone(), reasons));
        }

        Ok(UserPolicies::new_with_matches(
            principal_id,
            matching_policies,
        ))
    }

    pub fn policies(&self) -> Result<Vec<Policy>, PolicyError> {
        let snapshot = self.current_snapshot();
        Ok(snapshot.policy_set().policies().cloned().collect())
    }
}

#[cfg(test)]
mod tests;