zeph_subagent/

grants.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Zero-trust TTL-bounded permission grants for sub-agents.
//!
//! [`PermissionGrants`] tracks active grants (vault secrets or runtime tool access)
//! for a running sub-agent. All grants are time-limited; expired grants are swept
//! lazily by [`PermissionGrants::is_active`] and eagerly by
//! [`PermissionGrants::sweep_expired`].
//!
//! Grants are revoked on drop and on agent completion/cancellation. Secret key names
//! are never logged above DEBUG level; the `Display` impl for [`GrantKind::Secret`]
//! always prints `"Secret(<redacted>)"`.

use std::time::{Duration, Instant};

use serde::{Deserialize, Serialize};
use zeph_common::secret::Secret;

/// Metadata sent by a sub-agent when it needs a secret from the vault.
///
/// Carried in an `InputRequired` A2A status update as structured metadata.
/// The parent agent surfaces this to the user as an approval prompt; the user can
/// then call [`SubAgentManager::approve_secret`][crate::SubAgentManager] or
/// [`SubAgentManager::deny_secret`][crate::SubAgentManager].
///
/// # Examples
///
/// ```rust
/// use zeph_subagent::grants::SecretRequest;
///
/// let req = SecretRequest {
///     secret_key: "OPENAI_API_KEY".to_owned(),
///     reason: Some("needed for embeddings".to_owned()),
/// };
/// assert_eq!(req.secret_key, "OPENAI_API_KEY");
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SecretRequest {
    /// The vault key name the sub-agent is requesting.
    pub secret_key: String,
    /// Human-readable reason (shown to the user in the approval prompt).
    pub reason: Option<String>,
}

/// Identifies the kind of permission that was granted to a sub-agent.
///
/// `GrantKind` is intentionally NOT serializable — grant metadata should never
/// leave the in-memory security boundary. Key names are logged only at DEBUG
/// level to avoid leaking grant enumeration to centralized log systems.
///
/// The [`Display`][std::fmt::Display] implementation always redacts `Secret` payloads,
/// printing `Secret(<redacted>)` instead of the actual key name.
///
/// # Examples
///
/// ```rust
/// use zeph_subagent::grants::GrantKind;
///
/// let secret = GrantKind::Secret("my-key".to_owned());
/// assert!(!secret.to_string().contains("my-key"), "key must be redacted");
///
/// let tool = GrantKind::Tool("shell".to_owned());
/// assert_eq!(tool.to_string(), "Tool(shell)");
/// ```
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GrantKind {
    /// A vault secret key granted for in-memory access.
    Secret(String),
    /// A tool name granted at runtime beyond the definition's static policy.
    Tool(String),
}

impl std::fmt::Display for GrantKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Secret(_) => write!(f, "Secret(<redacted>)"),
            Self::Tool(name) => write!(f, "Tool({name})"),
        }
    }
}

/// A single permission grant with a TTL.
///
/// Created via [`PermissionGrants::add`] and swept automatically by
/// [`PermissionGrants::sweep_expired`].
#[derive(Debug)]
pub struct Grant {
    pub(crate) kind: GrantKind,
    pub(crate) granted_at: Instant,
    pub(crate) ttl: Duration,
}

impl Grant {
    /// Create a new grant for `kind` that expires after `ttl`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::time::Duration;
    /// use zeph_subagent::grants::{Grant, GrantKind};
    ///
    /// let grant = Grant::new(GrantKind::Tool("shell".to_owned()), Duration::from_mins(1));
    /// assert!(!grant.is_expired());
    /// ```
    #[must_use]
    pub fn new(kind: GrantKind, ttl: Duration) -> Self {
        Self {
            kind,
            granted_at: Instant::now(),
            ttl,
        }
    }

    /// Returns `true` if the grant's TTL has elapsed.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::time::Duration;
    /// use zeph_subagent::grants::{Grant, GrantKind};
    ///
    /// let grant = Grant::new(GrantKind::Tool("web".to_owned()), Duration::from_mins(5));
    /// // A brand-new grant is not yet expired.
    /// assert!(!grant.is_expired());
    /// ```
    #[must_use]
    pub fn is_expired(&self) -> bool {
        self.granted_at.elapsed() >= self.ttl
    }
}

/// Tracks active zero-trust permission grants for a sub-agent.
///
/// All grants are TTL-bounded. [`is_active`](Self::is_active) automatically
/// sweeps expired grants before checking, so callers do not need to call
/// [`sweep_expired`](Self::sweep_expired) manually.
#[derive(Debug, Default)]
pub struct PermissionGrants {
    grants: Vec<Grant>,
}

impl Drop for PermissionGrants {
    fn drop(&mut self) {
        // Defense-in-depth: revoke all grants on drop even if revoke_all()
        // was not explicitly called (e.g., on panic or early return).
        if !self.grants.is_empty() {
            tracing::warn!(
                count = self.grants.len(),
                "PermissionGrants dropped with active grants — revoking"
            );
            self.grants.clear();
        }
    }
}

impl PermissionGrants {
    /// Add a new grant with the given `kind` and `ttl`.
    ///
    /// The grant is immediately tracked. Expired grants are not swept here;
    /// call [`sweep_expired`][Self::sweep_expired] or [`is_active`][Self::is_active]
    /// to remove stale entries.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::time::Duration;
    /// use zeph_subagent::grants::{GrantKind, PermissionGrants};
    ///
    /// let mut grants = PermissionGrants::default();
    /// grants.add(GrantKind::Tool("shell".to_owned()), Duration::from_mins(1));
    /// assert!(grants.is_active(&GrantKind::Tool("shell".to_owned())));
    /// ```
    pub fn add(&mut self, kind: GrantKind, ttl: Duration) {
        // Log tool grants at DEBUG; for secrets log only the redacted display form.
        tracing::debug!(kind = %kind, ?ttl, "permission grant added");
        self.grants.push(Grant::new(kind, ttl));
    }

    /// Remove all expired grants.
    pub fn sweep_expired(&mut self) {
        let expired: Vec<_> = self.grants.extract_if(.., |g| g.is_expired()).collect();
        for g in &expired {
            tracing::debug!(kind = %g.kind, "permission grant expired and revoked");
        }
        if !expired.is_empty() {
            tracing::debug!(removed = expired.len(), "swept expired grants");
        }
    }

    /// Check if a specific grant is still active (not expired).
    ///
    /// Automatically sweeps expired grants before checking.
    #[must_use]
    pub fn is_active(&mut self, kind: &GrantKind) -> bool {
        self.sweep_expired();
        self.grants.iter().any(|g| &g.kind == kind)
    }

    /// Returns the absolute instant at which the active grant for `kind` expires.
    ///
    /// Automatically sweeps expired grants before checking, so a `None` result means
    /// there is no active grant for `kind` (never granted, already expired, or revoked).
    /// Used by [`SubAgentManager::deliver_secret`][crate::manager::SubAgentManager::deliver_secret]
    /// to stamp the delivered value with its expiry so the sub-agent loop can re-validate the
    /// TTL locally on every subsequent tool call, without needing further access to this
    /// `PermissionGrants` instance (which stays on the manager side, not the spawned loop task).
    ///
    /// If duplicate grants exist for the same `kind`, this returns the *first* match's
    /// expiry rather than the latest (max) one. This is intentionally fail-safe: it can
    /// only cause an earlier-than-necessary secret eviction in the sub-agent loop, never
    /// a later one, so it is not a security concern — just a minor inefficiency in the
    /// rare duplicate-grant case.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::time::Duration;
    /// use zeph_subagent::grants::{GrantKind, PermissionGrants};
    ///
    /// let mut grants = PermissionGrants::default();
    /// let kind = GrantKind::Secret("api-key".to_owned());
    /// assert!(grants.expires_at(&kind).is_none());
    ///
    /// grants.add(kind.clone(), Duration::from_mins(5));
    /// assert!(grants.expires_at(&kind).is_some());
    /// ```
    #[must_use]
    pub fn expires_at(&mut self, kind: &GrantKind) -> Option<Instant> {
        self.sweep_expired();
        self.grants
            .iter()
            .find(|g| &g.kind == kind)
            .map(|g| g.granted_at + g.ttl)
    }

    /// Grant access to a vault secret with the given TTL.
    ///
    /// Sweeps expired grants first. Logs an audit event at DEBUG (key is redacted
    /// in the log output to avoid leaking grant enumeration to log aggregators).
    pub fn grant_secret(&mut self, key: impl Into<String>, ttl: Duration) {
        self.sweep_expired();
        let key = key.into();
        tracing::debug!("vault secret granted to sub-agent (key redacted), ttl={ttl:?}");
        self.add(GrantKind::Secret(key), ttl);
    }

    /// Returns `true` if there are any grants currently tracked (expired or not).
    ///
    /// Used by [`Drop`] to emit a warning when handles are dropped without cleanup.
    #[must_use]
    pub fn is_empty_grants(&self) -> bool {
        self.grants.is_empty()
    }

    /// Revoke all grants immediately (called on sub-agent completion or cancellation).
    pub fn revoke_all(&mut self) {
        let count = self.grants.len();
        self.grants.clear();
        if count > 0 {
            tracing::debug!(count, "all permission grants revoked");
        }
    }
}

/// A resolved secret value delivered to a sub-agent loop, paired with the absolute
/// instant its originating grant expires.
///
/// Sent over the `secret_tx`/`secret_rx` channel
/// (see [`SubAgentHandle::secret_tx`][crate::manager::SubAgentHandle::secret_tx]) instead of a
/// bare [`Secret`] so the spawned agent loop task — which has no further access to the
/// manager-side [`PermissionGrants`] once the value is delivered — can still re-validate the
/// TTL locally before every tool call and evict the value once it expires.
///
/// # Examples
///
/// ```rust
/// use std::time::{Duration, Instant};
/// use zeph_common::secret::Secret;
/// use zeph_subagent::grants::GrantedSecret;
///
/// let granted = GrantedSecret {
///     value: Secret::new("sekrit"),
///     expires_at: Instant::now() + Duration::from_mins(5),
/// };
/// assert!(!granted.is_expired());
/// ```
#[derive(Debug)]
pub struct GrantedSecret {
    /// The resolved vault secret value.
    pub value: Secret,
    /// The absolute instant after which this value must no longer be used.
    pub expires_at: Instant,
}

impl GrantedSecret {
    /// Returns `true` if `expires_at` has already passed.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::time::{Duration, Instant};
    /// use zeph_common::secret::Secret;
    /// use zeph_subagent::grants::GrantedSecret;
    ///
    /// let expired = GrantedSecret {
    ///     value: Secret::new("sekrit"),
    ///     expires_at: Instant::now().checked_sub(Duration::from_secs(1)).unwrap(),
    /// };
    /// assert!(expired.is_expired());
    /// ```
    #[must_use]
    pub fn is_expired(&self) -> bool {
        Instant::now() >= self.expires_at
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn grant_is_active_before_expiry() {
        let mut pg = PermissionGrants::default();
        pg.add(GrantKind::Secret("api-key".into()), Duration::from_mins(5));
        assert!(pg.is_active(&GrantKind::Secret("api-key".into())));
    }

    #[test]
    fn sweep_expired_removes_instant_ttl() {
        let mut pg = PermissionGrants::default();
        pg.grants.push(Grant {
            kind: GrantKind::Tool("shell".into()),
            granted_at: Instant::now().checked_sub(Duration::from_secs(10)).unwrap(),
            ttl: Duration::from_secs(1), // already expired
        });
        // is_active internally sweeps
        assert!(!pg.is_active(&GrantKind::Tool("shell".into())));
        assert!(pg.grants.is_empty());
    }

    #[test]
    fn revoke_all_clears_all_grants() {
        let mut pg = PermissionGrants::default();
        pg.add(GrantKind::Secret("token".into()), Duration::from_mins(1));
        pg.add(GrantKind::Tool("web".into()), Duration::from_mins(1));
        pg.revoke_all();
        assert!(pg.grants.is_empty());
    }

    #[test]
    fn grant_secret_is_active() {
        let mut pg = PermissionGrants::default();
        pg.grant_secret("db-password", Duration::from_mins(2));
        assert!(pg.is_active(&GrantKind::Secret("db-password".into())));
    }

    #[test]
    fn whitespace_description_invalid() {
        // Verify grant kind display redacts secrets
        let k = GrantKind::Secret("my-secret-key".into());
        let display = k.to_string();
        assert!(
            !display.contains("my-secret-key"),
            "secret key must be redacted in Display"
        );
        assert!(display.contains("redacted"));
    }

    #[test]
    fn tool_grant_display_shows_name() {
        let k = GrantKind::Tool("shell".into());
        assert_eq!(k.to_string(), "Tool(shell)");
    }

    #[test]
    fn partial_sweep_keeps_non_expired_grants() {
        let mut pg = PermissionGrants::default();

        // Add one already-expired grant.
        pg.grants.push(Grant {
            kind: GrantKind::Tool("expired-tool".into()),
            granted_at: Instant::now().checked_sub(Duration::from_secs(10)).unwrap(),
            ttl: Duration::from_secs(1),
        });

        // Add one live grant with long TTL.
        pg.add(GrantKind::Secret("live-key".into()), Duration::from_mins(5));

        pg.sweep_expired();

        assert_eq!(pg.grants.len(), 1, "only live grant should remain");
        assert_eq!(pg.grants[0].kind, GrantKind::Secret("live-key".into()));
    }

    #[test]
    fn duplicate_grant_for_same_key_both_tracked() {
        let mut pg = PermissionGrants::default();
        pg.add(GrantKind::Secret("my-key".into()), Duration::from_mins(1));
        pg.add(GrantKind::Secret("my-key".into()), Duration::from_mins(1));

        // Both grants are stored; is_active just checks any match.
        assert_eq!(pg.grants.len(), 2);
        assert!(pg.is_active(&GrantKind::Secret("my-key".into())));

        // After revoking all, none remain.
        pg.revoke_all();
        assert!(pg.grants.is_empty());
    }
}