zlayer-types 0.13.0

//! JWT claims and related auth wire types.
//!
//! Lifted from `zlayer-api` so cross-crate consumers (`zlayer-agent`,
//! the CLI, future federation code) can name the JWT claims without
//! depending on `zlayer-api`. Token signing/verification helpers stay
//! in `zlayer-api::auth`.

use serde::{Deserialize, Serialize};
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use crate::storage::{PermissionLevel, TokenScope};

/// JWT claims used by every protected endpoint.
///
/// `node_id` is `Some` only on node JWTs — tokens issued by the leader
/// during cluster join with `roles: ["node"]` so a node can authenticate
/// to its peers' internal endpoints distinct from any user identity.
/// All other JWT issuers leave it `None`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Claims {
    /// Subject — user id, api-key id, or `"node:{node_id}"` for node JWTs.
    pub sub: String,

    /// Expiration time (Unix seconds).
    pub exp: u64,

    /// Issued at (Unix seconds).
    pub iat: u64,

    /// Issuer (canonically `"zlayer"`; federation will use a cluster-id form).
    pub iss: String,

    /// Role claims, e.g. `["admin"]`, `["operator"]`, `["node"]`.
    ///
    /// `#[serde(default)]` preserves back-compat with tokens minted before
    /// the field existed.
    #[serde(default)]
    pub roles: Vec<String>,

    /// Email — embedded for session JWTs so the manager UI doesn't
    /// have to round-trip to the user store on every request.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,

    /// Cluster-wide node UUID. `Some` only for JWTs minted by the
    /// leader at cluster-join time (where `roles` contains `"node"`).
    /// All other token kinds leave this `None`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_id: Option<String>,

    /// Least-privilege scope grants baked into the token. Empty for human /
    /// admin / node tokens (whose authority comes from `roles`); non-empty for
    /// scoped access tokens minted for containers, jobs, or CI runners. When
    /// non-empty, the token is authorized for a request only if some scope
    /// [`TokenScope::satisfies`] it (an `admin` role still short-circuits).
    ///
    /// `#[serde(default)]` keeps back-compat with pre-scope tokens.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub scopes: Vec<TokenScope>,

    /// Token id — the revocation handle. `Some` only on managed scoped tokens
    /// that have a [`crate::storage::StoredAccessToken`] record; the auth layer
    /// rejects the token if its `jti` has been revoked. Human/node tokens leave
    /// this `None` and skip the revocation lookup (stateless fast path).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub jti: Option<String>,
}

impl Claims {
    /// Create new claims.
    ///
    /// `node_id` is left `None`; node JWTs are constructed via struct
    /// literal at the cluster-join site.
    ///
    /// # Panics
    ///
    /// Panics if the system clock is before the Unix epoch.
    pub fn new(
        subject: impl Into<String>,
        expiry: Duration,
        roles: Vec<String>,
        email: Option<String>,
    ) -> Self {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("system clock before Unix epoch")
            .as_secs();

        Self {
            sub: subject.into(),
            exp: now + expiry.as_secs(),
            iat: now,
            iss: "zlayer".to_string(),
            roles,
            email,
            node_id: None,
            scopes: Vec::new(),
            jti: None,
        }
    }

    /// Create claims for a scoped access token: an attenuated bearer carrying
    /// `scopes` and a `jti` revocation handle. `roles` is usually empty (or a
    /// non-`admin` marker); authority comes from `scopes`.
    ///
    /// # Panics
    ///
    /// Panics if the system clock is before the Unix epoch.
    pub fn new_scoped(
        subject: impl Into<String>,
        expiry: Duration,
        roles: Vec<String>,
        scopes: Vec<TokenScope>,
        jti: impl Into<String>,
    ) -> Self {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("system clock before Unix epoch")
            .as_secs();

        Self {
            sub: subject.into(),
            exp: now + expiry.as_secs(),
            iat: now,
            iss: "zlayer".to_string(),
            roles,
            email: None,
            node_id: None,
            scopes,
            jti: Some(jti.into()),
        }
    }

    /// Check if token is expired.
    ///
    /// # Panics
    ///
    /// Panics if the system clock is before the Unix epoch.
    #[must_use]
    pub fn is_expired(&self) -> bool {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("system clock before Unix epoch")
            .as_secs();
        self.exp < now
    }

    /// Check if the user has a specific role
    #[must_use]
    pub fn has_role(&self, role: &str) -> bool {
        self.roles.iter().any(|r| r == role || r == "admin")
    }

    /// Whether this token is a scoped access token (carries embedded scopes).
    #[must_use]
    pub fn is_scoped(&self) -> bool {
        !self.scopes.is_empty()
    }

    /// Whether the token authorizes `level` access to
    /// `(resource_kind, resource_id)`.
    ///
    /// An `admin` role short-circuits to `true`. Otherwise authorization is
    /// granted iff some embedded [`TokenScope`] satisfies the request. A token
    /// with no scopes and no `admin` role returns `false` here — non-scoped
    /// human authority is decided by role/permission checks elsewhere, not by
    /// this method.
    #[must_use]
    pub fn satisfies(
        &self,
        resource_kind: &str,
        resource_id: Option<&str>,
        level: PermissionLevel,
    ) -> bool {
        if self.roles.iter().any(|r| r == "admin") {
            return true;
        }
        self.scopes
            .iter()
            .any(|s| s.satisfies(resource_kind, resource_id, level))
    }
}