khive-gate 0.9.0

use std::sync::Arc;

use crate::{ActorRef, GateDecision, GateError, GateRequest};

/// Authorization gate consulted before each verb dispatch.
///
/// Implementations return policy denials as decisions and infrastructure failures as errors. See
/// `crates/khive-gate/docs/api/gate-evaluation.md`.
/// Request arguments are submitted, pre-handler values. Canonicalization and
/// kind hooks may rewrite them after this decision; policies requiring the
/// effective values must be enforced by the handler after normalization.
pub trait Gate: Send + Sync + std::fmt::Debug {
    /// Evaluate `req`, returning an allow/deny decision or a backend [`GateError`].
    fn check(&self, req: &GateRequest) -> Result<GateDecision, GateError>;

    /// Evaluate the separate capability to read another actor's mailbox.
    ///
    /// Ordinary request admission never grants this capability, including an
    /// [`AllowAllGate`]. Callers must also retain the result of [`Gate::check`].
    fn check_mailbox_read(
        &self,
        _req: &GateRequest,
        _owner: &ActorRef,
    ) -> Result<GateDecision, GateError> {
        Ok(GateDecision::deny("mailbox_read_not_granted"))
    }

    /// Return the audit backend name; defaults to `std::any::type_name::<Self>()`.
    fn impl_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }

    /// Return an opaque, deterministic fingerprint when this gate's policy
    /// must participate in warm-daemon identity.
    ///
    /// The default preserves the legacy identity of programmatically supplied
    /// gates whose configuration is managed outside khive. Built-in gates with
    /// construction-baked policy override this so a stale daemon can never
    /// serve requests under a different policy.
    fn configuration_fingerprint(&self) -> Option<&str> {
        None
    }
}

/// Shareable handle to a `Gate` impl.
pub type GateRef = Arc<dyn Gate>;

/// Permissive gate — every request is allowed with no obligations.
///
/// This runtime default is for trusted local use. See
/// `crates/khive-gate/docs/api/gate-evaluation.md`.
#[derive(Clone, Debug, Default)]
pub struct AllowAllGate;

impl Gate for AllowAllGate {
    fn check(&self, _req: &GateRequest) -> Result<GateDecision, GateError> {
        Ok(GateDecision::allow())
    }

    fn impl_name(&self) -> &'static str {
        "AllowAllGate"
    }
}