liminal-server 0.20.1

//! 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 routes;
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",
        }
    }
}

/// The grant a refusal says is needed: Lys's `needed` member, exactly.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NeededGrant {
    /// The app whose schema names the kind.
    pub app: String,
    /// The qualified kind, `<app>.<kind>`.
    pub kind: String,
    /// The exact resource id.
    pub id: String,
    /// The action needed on it.
    pub action: String,
}

/// The four shared refusal fields, in the bytes Lys's `Refused` has.
///
/// `resource` is `<qualified kind>:<id>`, `action` the action name,
/// `needed` the grant to ask for, `request` the Lys URL that asks for it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequiredGrant {
    /// `<qualified kind>:<id>` of the resource the caller needs.
    pub resource: String,
    /// The action needed.
    pub action: String,
    /// The grant to ask for.
    pub needed: NeededGrant,
    /// Request page supplied by the authority consumer.
    pub request: String,
}

impl RequiredGrant {
    /// The exact resource id behind `resource`.
    #[must_use]
    pub fn resource_id(&self) -> &str {
        self.resource
            .split_once(':')
            .map_or(self.resource.as_str(), |(_, id)| id)
    }
}

/// Shared refusal envelope; no credential or payload bytes. Its JSON is
/// byte-identical to lys-pass's `Refusal` for the same target.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AccessRefusal {
    /// Required resource/action and the request page, boxed so a refusal
    /// stays small inside every `Result` that carries it.
    pub refused: Box<RequiredGrant>,
}

impl AccessRefusal {
    /// Builds the common envelope for one of liminal's own resources.
    #[must_use]
    pub fn new(resource: AccessResource, action: AccessAction, request: String) -> Self {
        let AccessResource { kind, id } = resource;
        Self::for_target(LYS_APP, kind.qualified(), &id, action.name(), request)
    }

    /// Builds the envelope for any app's target, as the conformance harness
    /// and the link routes need.
    #[must_use]
    pub fn for_target(app: &str, kind: &str, id: &str, action: &str, request: String) -> Self {
        Self {
            refused: Box::new(RequiredGrant {
                resource: format!("{kind}:{id}"),
                action: action.to_owned(),
                needed: NeededGrant {
                    app: app.to_owned(),
                    kind: kind.to_owned(),
                    id: id.to_owned(),
                    action: action.to_owned(),
                },
                request,
            }),
        }
    }
}

/// Typed cause retained beside the common wire envelope.
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
pub enum RefusalCause {
    /// No applicable grant reaches the target.
    #[error("required grant is missing")]
    MissingGrant,
    /// The admitted pass is no longer current.
    #[error("pass lifetime has expired")]
    Expired,
    /// The pass was issued for another product.
    #[error("pass audience is not liminal")]
    WrongAudience,
    /// Offline signature verification failed.
    #[error("pass signature was refused")]
    Signature,
    /// An ancestor's grant does not flow through this placement.
    #[error("subject placement is restricted")]
    RestrictedPlacement,
    /// A draft or two-person mode cannot authorize hot work.
    #[error("grant mode cannot authorize a hot action")]
    HotMode,
    /// A deliberate decision cannot be made from a cached pass.
    #[error("lys_could_not_be_asked")]
    DeliberateUnavailable,
}

/// A typed refusal whose wire representation is the shared envelope.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("{cause}")]
pub struct AccessDecisionError {
    /// Precise refusal category.
    pub cause: RefusalCause,
    /// Common resource/action/request envelope.
    pub refusal: AccessRefusal,
}

/// 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
    }

    /// 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 {
    /// 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>;
}

/// Single-valued permission class declared by a data route.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "class", rename_all = "snake_case")]
pub enum AccessRouteClass {
    /// Offline publication.
    Publish,
    /// Offline subscription.
    Subscribe,
    /// Offline service call.
    Call,
    /// Offline service serving.
    Serve,
    /// A live-only act with the schema's declared approval mode.
    Deliberate {
        /// Mode declared for this route; the live grant determines the outcome.
        mode: GrantMode,
    },
}

impl AccessRouteClass {
    /// Returns an offline action only for an explicitly hot route.
    #[must_use]
    pub const fn hot_action(self) -> Option<HotAction> {
        match self {
            Self::Publish => Some(HotAction::Publish),
            Self::Subscribe => Some(HotAction::Subscribe),
            Self::Call => Some(HotAction::Call),
            Self::Serve => Some(HotAction::Serve),
            Self::Deliberate { .. } => None,
        }
    }
}