liminal-server 0.25.4

//! Subject decisions delegated to the shared pass consumer.
//!
//! Product resource bindings come from admitted placements, never from splitting
//! subject spelling. The consumer owns verification and placement reach.

use serde::{Deserialize, Serialize};

pub mod live;
pub mod lys_pass_adapter;
pub mod prepared;
mod refusal;
pub mod root_presence;
pub mod root_presence_start;
pub mod routes;
pub use refusal::{AccessDecisionError, AccessRefusal, NeededGrant, RefusalCause, RequiredGrant};
pub mod session;

/// Audience used for offline admission.
pub const LIMINAL_PASS_AUDIENCE: &str = "liminal";

/// Permission classification fixed by the product schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DecisionClass {
    /// Decided offline from the pass on each message.
    Hot,
    /// Requires the live authority and cannot use a hot fallback.
    Deliberate,
}

/// Actions shared by the subject, link and service consumers.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AccessAction {
    /// Publish a subject message.
    Publish,
    /// Subscribe to a subject.
    Subscribe,
    /// Call a subject service.
    Call,
    /// Serve a subject service.
    Serve,
    /// Export a machine-held link.
    LinkExport,
    /// Import a machine-held link.
    LinkImport,
    /// Deploy a service.
    DeployService,
    /// Administer a resource.
    Admin,
}

impl AccessAction {
    /// Returns the fixed decision class.
    #[must_use]
    pub const fn class(self) -> DecisionClass {
        match self {
            Self::Publish | Self::Subscribe | Self::Call | Self::Serve => DecisionClass::Hot,
            Self::LinkExport | Self::LinkImport | Self::DeployService | Self::Admin => {
                DecisionClass::Deliberate
            }
        }
    }
}

/// The only actions accepted by the per-message offline seam.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum HotAction {
    /// Publish a message.
    Publish,
    /// Subscribe to a subject.
    Subscribe,
    /// Call a service.
    Call,
    /// Serve a service.
    Serve,
}

impl From<HotAction> for AccessAction {
    fn from(value: HotAction) -> Self {
        match value {
            HotAction::Publish => Self::Publish,
            HotAction::Subscribe => Self::Subscribe,
            HotAction::Call => Self::Call,
            HotAction::Serve => Self::Serve,
        }
    }
}

/// A deliberate action presented to the hot seam.
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
#[error("action {0:?} requires a live Lys decision")]
pub struct DeliberateAction(pub AccessAction);

impl TryFrom<AccessAction> for HotAction {
    type Error = DeliberateAction;
    fn try_from(value: AccessAction) -> Result<Self, Self::Error> {
        match value {
            AccessAction::Publish => Ok(Self::Publish),
            AccessAction::Subscribe => Ok(Self::Subscribe),
            AccessAction::Call => Ok(Self::Call),
            AccessAction::Serve => Ok(Self::Serve),
            AccessAction::LinkExport
            | AccessAction::LinkImport
            | AccessAction::DeployService
            | AccessAction::Admin => Err(DeliberateAction(value)),
        }
    }
}

/// Resource kinds registered by the product schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResourceKind {
    /// A network containing placed subjects.
    Network,
    /// A subject placed beneath its admitted parent or network.
    Subject,
    /// A machine-held link placed under a network.
    Link,
    /// A service placed under a network.
    Service,
}

/// Exact authority resource, independent of the subject's display spelling.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct AccessResource {
    /// Registered product resource kind.
    pub kind: ResourceKind,
    /// Authority-issued resource identifier.
    pub id: String,
}

/// Explicit product mapping supplied from admitted resource placements.
///
/// This is a target mapping, not an authority token. Only the verified consumer
/// can decide that a pass reaches it.
#[derive(Debug, PartialEq, Eq)]
pub struct SubjectBinding {
    network_id: String,
    resource: AccessResource,
    subject: String,
}

/// An absent or pattern-based subject mapping.
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
#[error("invalid placed subject binding: {0}")]
pub struct SubjectBindingError(pub &'static str);

impl SubjectBinding {
    /// Checks an explicitly supplied mapping without deriving its parents.
    ///
    /// # Errors
    /// Refuses missing identifiers, whitespace and subject patterns.
    pub fn new(
        network_id: String,
        resource_id: String,
        subject: String,
    ) -> Result<Self, SubjectBindingError> {
        for (name, value) in [
            ("network", &network_id),
            ("resource", &resource_id),
            ("subject", &subject),
        ] {
            if value.is_empty()
                || value.chars().any(char::is_whitespace)
                || value.chars().any(char::is_control)
            {
                return Err(SubjectBindingError(name));
            }
        }
        if subject.contains(['*', '>']) {
            return Err(SubjectBindingError("subject pattern"));
        }
        Ok(Self {
            network_id,
            resource: AccessResource {
                kind: ResourceKind::Subject,
                id: resource_id,
            },
            subject,
        })
    }

    /// Returns the admitted network identity.
    #[must_use]
    pub fn network_id(&self) -> &str {
        self.network_id.as_str()
    }

    /// Borrows the exact subject resource.
    #[must_use]
    pub const fn resource(&self) -> &AccessResource {
        &self.resource
    }

    /// Returns the product subject mapped to that resource.
    #[must_use]
    pub fn subject(&self) -> &str {
        self.subject.as_str()
    }
}

/// The Lys app liminal registers its schema as.
pub const LYS_APP: &str = "liminal";

impl ResourceKind {
    /// The kind as Lys qualifies it: `<app>.<kind>`.
    #[must_use]
    pub const fn qualified(self) -> &'static str {
        match self {
            Self::Network => "liminal.network",
            Self::Subject => "liminal.subject",
            Self::Link => "liminal.link",
            Self::Service => "liminal.service",
        }
    }
}

impl AccessAction {
    /// The action's name in the schema and on the wire.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Publish => "publish",
            Self::Subscribe => "subscribe",
            Self::Call => "call",
            Self::Serve => "serve",
            Self::LinkExport => "link_export",
            Self::LinkImport => "link_import",
            Self::DeployService => "deploy_service",
            Self::Admin => "admin",
        }
    }
}

/// Grant to receipt in the product's operation log.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct GrantReceipt {
    /// Grant identity returned by the verified consumer.
    pub grant: String,
}

/// Shared-library integration seam, implemented by the pinned pass adapter.
///
/// Verification must authenticate signature, holder, audience and lifetime.
/// Hot decisions must recheck expiry on every invocation, evaluate only the
/// signed placement reach (including restricted children), require outright
/// mode, and return the actual granting identity. These methods perform no
/// network call. There is no product-side replacement rights evaluator.
pub trait LysPassConsumer {
    /// Opaque verified pass owned by the shared consumer.
    type Pass;
    /// Native verified holder representation owned by the shared consumer.
    type Holder: ?Sized;
    /// Original typed offline verification failure.
    type AdmissionError: std::error::Error;

    /// Verifies one credential offline for the required audience.
    ///
    /// # Errors
    /// Returns the consumer's original typed verification failure.
    fn verify_offline(
        &self,
        credential: &[u8],
        audience: &str,
        now: u64,
    ) -> Result<Self::Pass, Self::AdmissionError>;

    /// Borrows the holder proved by this same admitted credential.
    fn verified_holder<'p>(&self, pass: &'p Self::Pass) -> &'p Self::Holder;

    /// The directory kind of the holder this same credential proved
    /// (`person`, `agent`, ...), as the signed pass states it (ACCESS-006
    /// R1): an AI is asked about as its own agent identity, never as its
    /// responsible person. `None` when the consumer cannot name it, and a
    /// membership-protected channel then refuses by name.
    fn verified_holder_kind<'p>(&self, _pass: &'p Self::Pass) -> Option<&'p str> {
        None
    }

    /// When this same credential was issued, in Unix seconds, as the signed
    /// pass states it: a subject placed after it cannot be among its rights.
    /// `None` when the consumer cannot name it.
    fn verified_issued_at(&self, _pass: &Self::Pass) -> Option<u64> {
        None
    }

    /// Decides one exact subject/action from a current verified pass.
    ///
    /// # Errors
    /// Returns the common refusal with its exact typed cause.
    fn decide_hot(
        &self,
        pass: &Self::Pass,
        subject: &SubjectBinding,
        action: HotAction,
        now: u64,
    ) -> Result<GrantReceipt, AccessDecisionError>;

    /// Decides one link grant (`link_export` or `link_import`) on one exact
    /// bound subject from a current verified pass, offline (ACCESS-002 R1).
    ///
    /// # Errors
    /// Returns the common refusal with its exact typed cause.
    fn decide_link(
        &self,
        pass: &Self::Pass,
        subject: &SubjectBinding,
        action: crate::link::LinkAction,
        now: u64,
    ) -> Result<GrantReceipt, AccessDecisionError>;
}

/// A pass admitted only through the configured offline consumer.
pub struct AdmittedLysPass<P> {
    pass: P,
}

impl<P> std::fmt::Debug for AdmittedLysPass<P> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("AdmittedLysPass")
            .finish_non_exhaustive()
    }
}

/// Admits a second credential without changing the existing signed pass bytes.
///
/// # Errors
/// Preserves the shared consumer's typed verification failure.
pub fn admit_lys_pass<C: LysPassConsumer>(
    consumer: &C,
    credential: &[u8],
    now: u64,
) -> Result<AdmittedLysPass<C::Pass>, C::AdmissionError> {
    consumer
        .verify_offline(credential, LIMINAL_PASS_AUDIENCE, now)
        .map(|pass| AdmittedLysPass { pass })
}

/// Makes exactly one fresh offline decision for this message.
///
/// No admission-wide allow is cached. The adapter, rather than subject text,
/// selects the longest applicable placed ancestor and the actual granting right.
///
/// # Errors
/// Propagates the consumer's typed refusal unchanged.
pub fn decide_message<C: LysPassConsumer>(
    consumer: &C,
    pass: &AdmittedLysPass<C::Pass>,
    subject: &SubjectBinding,
    action: HotAction,
    now: u64,
) -> Result<GrantReceipt, AccessDecisionError> {
    consumer.decide_hot(&pass.pass, subject, action, now)
}

/// Grant mode selected by the authority, never a service-side default.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GrantMode {
    /// Execute under the returned grant.
    Outright,
    /// Hold for one approval.
    ByDraft,
    /// Hold for two distinct approvals.
    ByTwo,
}

/// A live decision; held acts have no permission to execute yet.
#[derive(Debug, PartialEq, Eq)]
pub enum DeliberateDecision {
    /// The live authority authorizes execution under this exact grant.
    Outright(GrantReceipt),
    /// The act is held as an authority-owned draft.
    ByDraft {
        /// Grant requiring approval.
        grant: String,
        /// Draft identity returned by the live authority.
        draft: String,
    },
    /// The act is held for two distinct approvals.
    ByTwo {
        /// Grant requiring two approvers.
        grant: String,
        /// Draft identity returned by the live authority.
        draft: String,
    },
}

/// Live-only decision seam shared with deliberately classified services.
///
/// The adapter authenticates the same admitted pass and the route's schema
/// classification. Unavailability must return `DeliberateUnavailable`, never a
/// cached allow or a hot decision.
pub trait LysDeliberateConsumer: LysPassConsumer {
    /// Holds an ACP permission using this admitted credential.
    ///
    /// # Errors
    /// Missing prepared support or an authenticated refusal.
    fn hold_permission(
        &self,
        _pass: &Self::Pass,
        _request: prepared::PermissionRequest<'_>,
    ) -> Result<serde_json::Value, lys_pass::Error> {
        Err(lys_pass::Error::CannotAsk(
            "prepared permission unavailable",
        ))
    }

    /// Holds exact construction words using the credential this consumer admitted.
    ///
    /// # Errors
    /// A consumer without prepared support refuses explicitly.
    fn hold_site(
        &self,
        _pass: &Self::Pass,
        _request: prepared::SiteRequest<'_>,
    ) -> Result<serde_json::Value, lys_pass::Error> {
        Err(lys_pass::Error::CannotAsk(
            "prepared construction unavailable",
        ))
    }

    /// Asks the live authority for this exact resource/action.
    ///
    /// # Errors
    /// Preserves the typed refusal, including authority unavailability.
    fn decide_live(
        &self,
        pass: &Self::Pass,
        resource: &AccessResource,
        action: AccessAction,
        now: u64,
    ) -> Result<DeliberateDecision, AccessDecisionError>;
}

/// Borrows the native holder established by this same offline verification.
#[must_use]
pub fn verified_lys_holder<'p, C: LysPassConsumer>(
    consumer: &C,
    pass: &'p AdmittedLysPass<C::Pass>,
) -> &'p C::Holder {
    consumer.verified_holder(&pass.pass)
}

/// Makes a live decision for a route explicitly classified deliberate.
///
/// The consumer must check that classification against the registered schema.
/// This function never attempts a hot fallback and never executes a held act.
///
/// # Errors
/// Propagates the live authority's typed refusal unchanged.
pub fn decide_deliberate<C: LysDeliberateConsumer>(
    consumer: &C,
    pass: &AdmittedLysPass<C::Pass>,
    resource: &AccessResource,
    action: AccessAction,
    now: u64,
) -> Result<DeliberateDecision, AccessDecisionError> {
    consumer.decide_live(&pass.pass, resource, action, now)
}

/// Read-only policy source; budget and stop policy remains authority-owned.
///
/// The concrete policy representation belongs to the shared authority adapter.
/// No local policy setter or budget decision is provided.
pub trait LysPolicySource {
    /// Native policy snapshot, without a product-side replacement shape.
    type Snapshot;
    /// Original typed policy read failure.
    type Error: std::error::Error;

    /// Reads policy for an exact authority resource.
    ///
    /// # Errors
    /// Preserves the authority's typed read or availability failure.
    fn read_policy(&self, resource: &AccessResource) -> Result<Self::Snapshot, Self::Error>;
}

#[path = "auth_lys/route_class.rs"]
mod route_class;

#[cfg(test)]
#[path = "auth_lys/root_presence_start_tests.rs"]
mod root_presence_start_tests;
#[cfg(test)]
#[path = "auth_lys/root_presence_tests.rs"]
mod root_presence_tests;
pub use route_class::AccessRouteClass;

pub use live::drafts;