cortex_store/repo/

authority.rs

//! Temporal authority timeline repository.

use chrono::{DateTime, Utc};
use cortex_core::{
    revalidate_temporal_authority, KeyLifecycleState, PolicyContribution, PolicyDecision,
    PolicyOutcome, TemporalAuthorityEvidence, TemporalAuthorityReport, TrustTier,
};
use rusqlite::{params, OptionalExtension, Row};

use crate::{Pool, StoreError, StoreResult};

/// Required contributor rule id documenting that an operator attested the
/// proposed key state transition (ADR 0019 §3, ADR 0026 §4).
pub const KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID: &str = "authority.key_state.attested_by_operator";
/// Required contributor rule id documenting that the trust tier gate composed
/// into the decision for this key state mutation (ADR 0019, ADR 0026 §4).
pub const KEY_STATE_TRUST_TIER_GATE_RULE_ID: &str = "authority.key_state.trust_tier_gate";
/// Required contributor rule id documenting that an operator attested the
/// principal trust tier promotion or downgrade (ADR 0019 §3, ADR 0026 §4).
pub const PRINCIPAL_STATE_ATTESTED_BY_OPERATOR_RULE_ID: &str =
    "authority.principal_state.attested_by_operator";
/// Required contributor rule id documenting that the trust tier gate composed
/// into the decision for this principal trust mutation (ADR 0019, ADR 0026 §4).
pub const PRINCIPAL_STATE_TRUST_TIER_GATE_RULE_ID: &str =
    "authority.principal_state.trust_tier_gate";
/// Required contributor rule id documenting that the proposed principal tier
/// is supported by a fresh tier promotion attestation (ADR 0019 §1, ADR 0026
/// §4). `BreakGlass` MUST NOT substitute for this contributor.
pub const PRINCIPAL_STATE_TIER_PROMOTION_ATTESTATION_RULE_ID: &str =
    "authority.principal_state.tier_promotion_attestation";

/// Key lifecycle timeline row.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KeyTimelineRecord {
    /// Key identifier.
    pub key_id: String,
    /// Principal bound to this key at the effective time.
    pub principal_id: String,
    /// Key lifecycle state.
    pub state: KeyLifecycleState,
    /// Effective time for this state.
    pub effective_at: DateTime<Utc>,
    /// Optional reason such as compromise/offboarding.
    pub reason: Option<String>,
    /// Optional audit row reference.
    pub audit_ref: Option<String>,
}

/// Principal trust timeline row.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PrincipalTimelineRecord {
    /// Principal identifier.
    pub principal_id: String,
    /// Trust tier effective from this row.
    pub trust_tier: TrustTier,
    /// Effective time for this state.
    pub effective_at: DateTime<Utc>,
    /// Optional trust review deadline.
    pub trust_review_due_at: Option<DateTime<Utc>>,
    /// Optional principal removal time.
    pub removed_at: Option<DateTime<Utc>>,
    /// Optional audit row reference.
    pub audit_ref: Option<String>,
}

/// Query for temporal authority revalidation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TemporalAuthorityQuery {
    /// Key identifier carried by the attestation.
    pub key_id: String,
    /// Signed event/audit time.
    pub event_time: DateTime<Utc>,
    /// Verification time.
    pub now: DateTime<Utc>,
    /// Minimum trust tier required for current use.
    pub minimum_trust_tier: TrustTier,
}

/// Repository for authority timelines.
#[derive(Debug)]
pub struct AuthorityRepo<'a> {
    pool: &'a Pool,
}

impl<'a> AuthorityRepo<'a> {
    /// Creates an authority repository over an open SQLite connection.
    #[must_use]
    pub const fn new(pool: &'a Pool) -> Self {
        Self { pool }
    }

    /// Append a key lifecycle timeline row through the ADR 0026 enforcement
    /// lattice.
    ///
    /// `policy` is the composed [`PolicyDecision`] for this key-state mutation
    /// and MUST satisfy:
    ///
    /// 1. The final outcome is one of [`PolicyOutcome::Allow`],
    ///    [`PolicyOutcome::Warn`], or [`PolicyOutcome::BreakGlass`]. A
    ///    `Quarantine` or `Reject` decision fails closed and writes nothing.
    /// 2. The composition includes contributors for both
    ///    [`KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID`] and
    ///    [`KEY_STATE_TRUST_TIER_GATE_RULE_ID`]. The repo refuses callers that
    ///    skipped composition.
    /// 3. Per ADR 0026 §4, the operator attestation contributor MUST be
    ///    [`PolicyOutcome::Allow`] even when the final decision is
    ///    `BreakGlass`. Break-glass never substitutes for operator attestation
    ///    at the key-state authority root.
    /// 4. The proposed [`KeyTimelineRecord::state`] is consistent with the
    ///    principal's current trust tier visible in the timeline. Activating a
    ///    new key for a principal that is below
    ///    [`TrustTier::Verified`] is refused.
    pub fn append_key_state(
        &self,
        record: &KeyTimelineRecord,
        policy: &PolicyDecision,
    ) -> StoreResult<()> {
        require_policy_final_outcome(policy, "authority.key_state")?;
        require_contributor_rule(policy, KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID)?;
        require_contributor_rule(policy, KEY_STATE_TRUST_TIER_GATE_RULE_ID)?;
        require_attestation_not_break_glassed(
            policy,
            KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID,
            "authority.key_state",
        )?;

        if matches!(record.state, KeyLifecycleState::Active) {
            self.reject_active_key_for_undertrust_principal(record)?;
        }

        self.pool.execute(
            "INSERT INTO authority_key_timeline (
                key_id, principal_id, state, effective_at, reason, audit_ref
             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6);",
            params![
                record.key_id,
                record.principal_id,
                key_state_wire(record.state),
                record.effective_at.to_rfc3339(),
                record.reason,
                record.audit_ref,
            ],
        )?;
        Ok(())
    }

    /// Append a principal trust timeline row through the ADR 0026 enforcement
    /// lattice.
    ///
    /// Same envelope as [`Self::append_key_state`] plus the
    /// [`PRINCIPAL_STATE_TIER_PROMOTION_ATTESTATION_RULE_ID`] contributor.
    /// ADR 0026 §4 is a hard wall: `BreakGlass` MUST NOT substitute for the
    /// tier promotion attestation. The repo enforces that the attestation
    /// contributor is `Allow` even when the final decision is `BreakGlass`.
    pub fn append_principal_state(
        &self,
        record: &PrincipalTimelineRecord,
        policy: &PolicyDecision,
    ) -> StoreResult<()> {
        require_policy_final_outcome(policy, "authority.principal_state")?;
        require_contributor_rule(policy, PRINCIPAL_STATE_ATTESTED_BY_OPERATOR_RULE_ID)?;
        require_contributor_rule(policy, PRINCIPAL_STATE_TRUST_TIER_GATE_RULE_ID)?;
        require_contributor_rule(policy, PRINCIPAL_STATE_TIER_PROMOTION_ATTESTATION_RULE_ID)?;
        require_attestation_not_break_glassed(
            policy,
            PRINCIPAL_STATE_ATTESTED_BY_OPERATOR_RULE_ID,
            "authority.principal_state",
        )?;
        require_attestation_not_break_glassed(
            policy,
            PRINCIPAL_STATE_TIER_PROMOTION_ATTESTATION_RULE_ID,
            "authority.principal_state",
        )?;

        self.pool.execute(
            "INSERT INTO authority_principal_timeline (
                principal_id, trust_tier, effective_at, trust_review_due_at, removed_at, audit_ref
             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6);",
            params![
                record.principal_id,
                trust_tier_wire(record.trust_tier),
                record.effective_at.to_rfc3339(),
                record.trust_review_due_at.map(|value| value.to_rfc3339()),
                record.removed_at.map(|value| value.to_rfc3339()),
                record.audit_ref,
            ],
        )?;
        Ok(())
    }

    fn reject_active_key_for_undertrust_principal(
        &self,
        record: &KeyTimelineRecord,
    ) -> StoreResult<()> {
        let current_trust = self.principal_state_at(&record.principal_id, record.effective_at)?;
        match current_trust {
            Some(state) if state.trust_tier < TrustTier::Verified => {
                Err(StoreError::Validation(format!(
                    "authority.key_state preflight: refuse to activate key `{}` for principal `{}` while current trust tier `{:?}` is below `Verified`",
                    record.key_id, record.principal_id, state.trust_tier,
                )))
            }
            // Unknown principal: caller must register the trust state first.
            None => Err(StoreError::Validation(format!(
                "authority.key_state preflight: refuse to activate key `{}` for principal `{}` without a current trust tier row",
                record.key_id, record.principal_id,
            ))),
            Some(_) => Ok(()),
        }
    }

    /// Revalidate a key's authority at event time and for current use.
    pub fn revalidate(
        &self,
        query: &TemporalAuthorityQuery,
    ) -> StoreResult<TemporalAuthorityReport> {
        let key_at_event = self.key_state_at(&query.key_id, query.event_time)?;
        let current_key_state = self.key_state_at(&query.key_id, query.now)?;
        let key_activated_at = self.key_state_effective_at(
            &query.key_id,
            KeyLifecycleState::Active,
            query.event_time,
        )?;
        let key_retired_at =
            self.key_state_effective_at(&query.key_id, KeyLifecycleState::Retired, query.now)?;
        let key_revoked_at =
            self.key_state_effective_at(&query.key_id, KeyLifecycleState::Revoked, query.now)?;
        let principal_id = key_at_event
            .as_ref()
            .or(current_key_state.as_ref())
            .map(|record| record.principal_id.clone());
        let trust_at_event = match principal_id.as_deref() {
            Some(principal_id) => self.principal_state_at(principal_id, query.event_time)?,
            None => None,
        };
        let current_trust = match principal_id.as_deref() {
            Some(principal_id) => self.principal_state_at(principal_id, query.now)?,
            None => None,
        };

        Ok(revalidate_temporal_authority(TemporalAuthorityEvidence {
            key_id: query.key_id.clone(),
            principal_id,
            event_time: query.event_time,
            now: query.now,
            key_activated_at,
            key_retired_at,
            key_revoked_at,
            trust_tier_at_event_time: trust_at_event.as_ref().map(|record| record.trust_tier),
            current_trust_tier: current_trust.as_ref().map(|record| record.trust_tier),
            current_trust_tier_effective_at: current_trust
                .as_ref()
                .map(|record| record.effective_at),
            minimum_trust_tier: query.minimum_trust_tier,
            principal_removed_at: current_trust.as_ref().and_then(|record| record.removed_at),
            trust_review_due_at: current_trust
                .as_ref()
                .and_then(|record| record.trust_review_due_at),
        }))
    }

    fn key_state_at(
        &self,
        key_id: &str,
        at: DateTime<Utc>,
    ) -> StoreResult<Option<KeyTimelineRecord>> {
        let row = self
            .pool
            .query_row(
                "SELECT key_id, principal_id, state, effective_at, reason, audit_ref
                 FROM authority_key_timeline
                 WHERE key_id = ?1 AND effective_at <= ?2
                 ORDER BY effective_at DESC, state DESC
                 LIMIT 1;",
                params![key_id, at.to_rfc3339()],
                key_timeline_row,
            )
            .optional()?;

        row.map(TryInto::try_into).transpose()
    }

    fn key_state_effective_at(
        &self,
        key_id: &str,
        state: KeyLifecycleState,
        at: DateTime<Utc>,
    ) -> StoreResult<Option<DateTime<Utc>>> {
        let value = self
            .pool
            .query_row(
                "SELECT effective_at
                 FROM authority_key_timeline
                 WHERE key_id = ?1 AND state = ?2 AND effective_at <= ?3
                 ORDER BY effective_at DESC
                 LIMIT 1;",
                params![key_id, key_state_wire(state), at.to_rfc3339()],
                |row| row.get::<_, String>(0),
            )
            .optional()?;

        value.as_deref().map(parse_utc).transpose()
    }

    fn principal_state_at(
        &self,
        principal_id: &str,
        at: DateTime<Utc>,
    ) -> StoreResult<Option<PrincipalTimelineRecord>> {
        let row = self
            .pool
            .query_row(
                "SELECT principal_id, trust_tier, effective_at, trust_review_due_at, removed_at, audit_ref
                 FROM authority_principal_timeline
                 WHERE principal_id = ?1 AND effective_at <= ?2
                 ORDER BY effective_at DESC
                 LIMIT 1;",
                params![principal_id, at.to_rfc3339()],
                principal_timeline_row,
            )
            .optional()?;

        row.map(TryInto::try_into).transpose()
    }
}

#[derive(Debug)]
struct KeyTimelineRow {
    key_id: String,
    principal_id: String,
    state: String,
    effective_at: String,
    reason: Option<String>,
    audit_ref: Option<String>,
}

fn key_timeline_row(row: &Row<'_>) -> rusqlite::Result<KeyTimelineRow> {
    Ok(KeyTimelineRow {
        key_id: row.get(0)?,
        principal_id: row.get(1)?,
        state: row.get(2)?,
        effective_at: row.get(3)?,
        reason: row.get(4)?,
        audit_ref: row.get(5)?,
    })
}

impl TryFrom<KeyTimelineRow> for KeyTimelineRecord {
    type Error = StoreError;

    fn try_from(row: KeyTimelineRow) -> StoreResult<Self> {
        Ok(Self {
            key_id: row.key_id,
            principal_id: row.principal_id,
            state: parse_key_state(&row.state)?,
            effective_at: parse_utc(&row.effective_at)?,
            reason: row.reason,
            audit_ref: row.audit_ref,
        })
    }
}

#[derive(Debug)]
struct PrincipalTimelineRow {
    principal_id: String,
    trust_tier: String,
    effective_at: String,
    trust_review_due_at: Option<String>,
    removed_at: Option<String>,
    audit_ref: Option<String>,
}

fn principal_timeline_row(row: &Row<'_>) -> rusqlite::Result<PrincipalTimelineRow> {
    Ok(PrincipalTimelineRow {
        principal_id: row.get(0)?,
        trust_tier: row.get(1)?,
        effective_at: row.get(2)?,
        trust_review_due_at: row.get(3)?,
        removed_at: row.get(4)?,
        audit_ref: row.get(5)?,
    })
}

impl TryFrom<PrincipalTimelineRow> for PrincipalTimelineRecord {
    type Error = StoreError;

    fn try_from(row: PrincipalTimelineRow) -> StoreResult<Self> {
        Ok(Self {
            principal_id: row.principal_id,
            trust_tier: parse_trust_tier(&row.trust_tier)?,
            effective_at: parse_utc(&row.effective_at)?,
            trust_review_due_at: row
                .trust_review_due_at
                .as_deref()
                .map(parse_utc)
                .transpose()?,
            removed_at: row.removed_at.as_deref().map(parse_utc).transpose()?,
            audit_ref: row.audit_ref,
        })
    }
}

fn require_policy_final_outcome(policy: &PolicyDecision, surface: &str) -> StoreResult<()> {
    match policy.final_outcome {
        PolicyOutcome::Allow | PolicyOutcome::Warn | PolicyOutcome::BreakGlass => Ok(()),
        PolicyOutcome::Quarantine | PolicyOutcome::Reject => Err(StoreError::Validation(format!(
            "{surface} preflight: composed policy outcome {:?} blocks authority-root mutation",
            policy.final_outcome,
        ))),
    }
}

fn require_contributor_rule(policy: &PolicyDecision, rule_id: &str) -> StoreResult<()> {
    let contains_rule = policy
        .contributing
        .iter()
        .chain(policy.discarded.iter())
        .any(|contribution| contribution.rule_id.as_str() == rule_id);
    if contains_rule {
        Ok(())
    } else {
        Err(StoreError::Validation(format!(
            "policy decision missing required contributor `{rule_id}`; caller skipped ADR 0026 composition",
        )))
    }
}

fn require_attestation_not_break_glassed(
    policy: &PolicyDecision,
    rule_id: &str,
    surface: &str,
) -> StoreResult<()> {
    // ADR 0026 §4: BreakGlass MUST NOT substitute for required attestation at
    // an authority root. The attestation contributor must itself have voted
    // `Allow` regardless of how the rest of the composition resolved.
    let attestation = policy
        .contributing
        .iter()
        .chain(policy.discarded.iter())
        .find(|contribution| contribution.rule_id.as_str() == rule_id)
        .ok_or_else(|| {
            StoreError::Validation(format!(
                "{surface} preflight: required attestation contributor `{rule_id}` is absent from the policy decision",
            ))
        })?;
    if attestation.outcome == PolicyOutcome::Allow {
        Ok(())
    } else {
        Err(StoreError::Validation(format!(
            "{surface} preflight: attestation contributor `{rule_id}` returned {:?}; ADR 0026 §4 forbids BreakGlass substituting for attestation",
            attestation.outcome,
        )))
    }
}

/// Build a `PolicyDecision` that satisfies [`AuthorityRepo::append_key_state`]
/// inputs for the happy path. Intended for tests and fixtures only.
///
/// Production callers MUST compose
/// [`KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID`] and
/// [`KEY_STATE_TRUST_TIER_GATE_RULE_ID`] from real attestation evidence and
/// real trust-tier state. This helper is exposed unconditionally because
/// integration test crates outside `cortex-store` need the same fixture
/// shape; the `_test_allow` suffix is the contract that documents intent.
#[must_use]
pub fn key_state_policy_decision_test_allow() -> PolicyDecision {
    use cortex_core::compose_policy_outcomes;
    compose_policy_outcomes(
        vec![
            PolicyContribution::new(
                KEY_STATE_ATTESTED_BY_OPERATOR_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: operator attestation present",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                KEY_STATE_TRUST_TIER_GATE_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: trust tier gate satisfied",
            )
            .expect("static test contribution is valid"),
        ],
        None,
    )
}

/// Build a `PolicyDecision` that satisfies
/// [`AuthorityRepo::append_principal_state`] inputs for the happy path.
/// Intended for tests and fixtures only; see
/// [`key_state_policy_decision_test_allow`] for the production-caller
/// contract.
#[must_use]
pub fn principal_state_policy_decision_test_allow() -> PolicyDecision {
    use cortex_core::compose_policy_outcomes;
    compose_policy_outcomes(
        vec![
            PolicyContribution::new(
                PRINCIPAL_STATE_ATTESTED_BY_OPERATOR_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: operator attestation present",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                PRINCIPAL_STATE_TRUST_TIER_GATE_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: trust tier gate satisfied",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                PRINCIPAL_STATE_TIER_PROMOTION_ATTESTATION_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: tier promotion attestation present",
            )
            .expect("static test contribution is valid"),
        ],
        None,
    )
}

fn parse_utc(value: &str) -> StoreResult<DateTime<Utc>> {
    Ok(DateTime::parse_from_rfc3339(value)?.with_timezone(&Utc))
}

fn key_state_wire(state: KeyLifecycleState) -> &'static str {
    match state {
        KeyLifecycleState::Active => "active",
        KeyLifecycleState::Retired => "retired",
        KeyLifecycleState::Revoked => "revoked",
    }
}

fn parse_key_state(value: &str) -> StoreResult<KeyLifecycleState> {
    match value {
        "active" => Ok(KeyLifecycleState::Active),
        "retired" => Ok(KeyLifecycleState::Retired),
        "revoked" => Ok(KeyLifecycleState::Revoked),
        other => Err(StoreError::Validation(format!(
            "unknown key lifecycle state `{other}`"
        ))),
    }
}

fn trust_tier_wire(tier: TrustTier) -> &'static str {
    match tier {
        TrustTier::Untrusted => "untrusted",
        TrustTier::Observed => "observed",
        TrustTier::Verified => "verified",
        TrustTier::Operator => "operator",
    }
}

fn parse_trust_tier(value: &str) -> StoreResult<TrustTier> {
    match value {
        "untrusted" => Ok(TrustTier::Untrusted),
        "observed" => Ok(TrustTier::Observed),
        "verified" => Ok(TrustTier::Verified),
        "operator" => Ok(TrustTier::Operator),
        other => Err(StoreError::Validation(format!(
            "unknown trust tier `{other}`"
        ))),
    }
}