byteor_app_kit/

approval.rs

use std::fmt;
use std::path::{Path, PathBuf};
use std::time::Duration;

use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
use byteor_core::config::Environment;
use ed25519_dalek::{Signature, Verifier as _, VerifyingKey};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use time::{format_description::well_known::Rfc3339, OffsetDateTime};

/// Derived approval state for a runtime spec after local credential verification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApprovalResolution {
    /// Whether the runtime may treat approval as present for policy evaluation.
    pub approval_token_present: bool,
    /// Capabilities inferred from the canonical spec that must be covered by the credential.
    pub required_capabilities: Vec<String>,
    /// Canonical `sha256:<hex>` digest of the runtime spec used for verification.
    pub spec_hash: String,
}

/// Source of the trusted signing keys currently available to the runtime.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApprovalTrustSource {
    /// The key set was refreshed while the control plane was reachable.
    Refreshed,
    /// The runtime is using its last locally cached key set.
    Cached,
}

/// A locally persisted trusted key set plus minimal refresh metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TrustedApprovalKeyCache {
    /// Source classification for the current key set.
    pub source: ApprovalTrustSource,
    /// When the key set was most recently refreshed online.
    pub last_refresh_at: Option<String>,
    /// Trusted signing keys available to the runtime.
    pub keys: Vec<TrustedApprovalKey>,
}

/// Trusted approval signing key material accepted by enterprise runtimes.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
pub struct TrustedApprovalKey {
    /// Stable key identifier announced by the control plane.
    pub kid: String,
    /// Signature algorithm name, currently `Ed25519`.
    pub algorithm: String,
    /// Public verification key in PEM/SPKI format.
    pub public_key_pem: String,
}

/// Control-plane bootstrap required to refresh trusted approval keys online.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApprovalRefreshBootstrap {
    /// Base URL for the control plane API, for example `https://control.example.com`.
    pub api_base_url: String,
    /// Agent ULID used for agent-scoped API requests.
    pub agent_id: String,
    /// Per-agent API key used for bearer authentication.
    pub agent_api_key: String,
}

#[derive(Debug, Deserialize)]
struct TrustedApprovalKeyEnvelope {
    keys: Vec<TrustedApprovalKey>,
}

#[derive(Debug, Deserialize, Serialize)]
struct TrustedApprovalKeyCacheEnvelope {
    source: ApprovalTrustSource,
    #[serde(default)]
    last_refresh_at: Option<String>,
    keys: Vec<TrustedApprovalKey>,
}

#[derive(Debug, Deserialize)]
struct SigningKeysResponseEnvelope {
    data: SigningKeysResponseData,
}

#[derive(Debug, Deserialize)]
struct SigningKeysResponseData {
    keys: Vec<TrustedApprovalKey>,
}

#[derive(Debug, Deserialize)]
struct ApprovalCredentialPayload {
    v: u32,
    kid: String,
    spec_hash: String,
    capabilities: Vec<String>,
    environment_posture: String,
    expires_at: String,
}

/// Errors returned when an approval credential cannot be verified locally.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApprovalVerificationError {
    /// No trusted signing keys were provided for credential verification.
    MissingKeySet,
    /// The credential was not formatted as `<payload>.<signature>`.
    InvalidFormat,
    /// The payload or signature segment was not valid base64url.
    InvalidBase64,
    /// The decoded payload was not valid approval credential JSON.
    InvalidPayloadJson,
    /// The credential version is not supported by this runtime.
    UnsupportedVersion(u32),
    /// The credential referenced a key id outside the trusted key set.
    UnknownKeyId(String),
    /// The trusted key advertised an unsupported signing algorithm.
    UnsupportedAlgorithm(String),
    /// The trusted key PEM could not be parsed into an Ed25519 verifying key.
    InvalidPublicKeyPem(String),
    /// The Ed25519 signature did not validate against the payload bytes.
    InvalidSignature,
    /// The credential's spec hash did not match the runtime spec hash.
    SpecHashMismatch,
    /// The credential's environment posture did not match the runtime environment.
    EnvironmentMismatch,
    /// The credential expiry time has passed.
    Expired,
    /// The credential did not cover every capability required by the runtime spec.
    InsufficientCapabilities(Vec<String>),
}

impl fmt::Display for ApprovalVerificationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::MissingKeySet => {
                write!(f, "approval key set required for credential verification")
            }
            Self::InvalidFormat => write!(f, "approval credential must be <payload>.<signature>"),
            Self::InvalidBase64 => write!(f, "approval credential is not valid base64url"),
            Self::InvalidPayloadJson => write!(f, "approval credential payload is not valid json"),
            Self::UnsupportedVersion(version) => {
                write!(f, "unsupported approval credential version {version}")
            }
            Self::UnknownKeyId(kid) => write!(f, "approval signing key {kid} is not trusted"),
            Self::UnsupportedAlgorithm(algorithm) => {
                write!(f, "unsupported approval signing algorithm {algorithm}")
            }
            Self::InvalidPublicKeyPem(kid) => {
                write!(f, "approval signing key {kid} has invalid public key pem")
            }
            Self::InvalidSignature => write!(f, "approval credential signature is invalid"),
            Self::SpecHashMismatch => write!(
                f,
                "approval credential spec hash does not match runtime spec"
            ),
            Self::EnvironmentMismatch => {
                write!(
                    f,
                    "approval credential environment does not match runtime environment"
                )
            }
            Self::Expired => write!(f, "approval credential has expired"),
            Self::InsufficientCapabilities(capabilities) => write!(
                f,
                "approval credential is missing required capabilities: {}",
                capabilities.join(", ")
            ),
        }
    }
}

impl std::error::Error for ApprovalVerificationError {}

/// Resolve runtime approval presence by verifying an optional credential against the
/// canonical spec hash, target environment, and required side-effect capabilities.
pub fn resolve_runtime_approval(
    canonical_spec_kv: &str,
    env: Environment,
    approval_credential: Option<&str>,
    trusted_keys: &[TrustedApprovalKey],
) -> Result<ApprovalResolution, ApprovalVerificationError> {
    let required_capabilities = required_approval_capabilities_for_spec_kv(canonical_spec_kv);
    let spec_hash = approval_spec_hash_from_canonical_spec_kv(canonical_spec_kv);

    let approval_token_present = match approval_credential {
        Some(credential) => {
            verify_approval_credential(
                credential,
                trusted_keys,
                &spec_hash,
                environment_posture(env),
                &required_capabilities,
            )?;
            true
        }
        None => false,
    };

    Ok(ApprovalResolution {
        approval_token_present,
        required_capabilities,
        spec_hash,
    })
}

/// Load trusted approval signing keys from one or more json files.
pub fn load_trusted_approval_keys_from_paths(
    paths: &[impl AsRef<Path>],
) -> Result<Vec<TrustedApprovalKey>, String> {
    let mut keys = Vec::new();
    for path in paths {
        keys.extend(load_trusted_approval_keys_from_file(path.as_ref())?);
    }
    Ok(keys)
}

/// Return default signing-key file locations associated with a spec path.
pub fn discover_trusted_approval_key_paths(spec_path: &Path) -> Vec<PathBuf> {
    let Some(candidate) = default_trusted_approval_key_cache_path(spec_path) else {
        return Vec::new();
    };
    if candidate.is_file() {
        vec![candidate]
    } else {
        Vec::new()
    }
}

/// Return the default local cache path used for trusted signing keys next to a spec file.
pub fn default_trusted_approval_key_cache_path(spec_path: &Path) -> Option<PathBuf> {
    Some(spec_path.parent()?.join("signing_keys.json"))
}

/// Return the default local path used for a bundle-adjacent approval credential.
pub fn default_approval_credential_path(spec_path: &Path) -> Option<PathBuf> {
    Some(spec_path.parent()?.join("approval.cred"))
}

/// Load an approval credential from an extracted deploy bundle when present.
pub fn load_approval_credential_from_bundle(spec_path: &Path) -> Result<Option<String>, String> {
    let Some(path) = default_approval_credential_path(spec_path) else {
        return Ok(None);
    };
    if !path.is_file() {
        return Ok(None);
    }

    let credential = std::fs::read_to_string(&path)
        .map_err(|error| format!("read approval credential {}: {error}", path.display()))?;
    let trimmed = credential.trim();
    if trimmed.is_empty() {
        return Ok(None);
    }

    Ok(Some(trimmed.to_string()))
}

/// Load trusted approval signing keys from a json file.
pub fn load_trusted_approval_keys_from_file(
    path: &Path,
) -> Result<Vec<TrustedApprovalKey>, String> {
    Ok(load_trusted_approval_key_cache_from_file(path)?.keys)
}

/// Load a trusted approval key cache envelope from disk.
pub fn load_trusted_approval_key_cache_from_file(
    path: &Path,
) -> Result<TrustedApprovalKeyCache, String> {
    let raw = std::fs::read_to_string(path)
        .map_err(|error| format!("read approval key set {}: {error}", path.display()))?;

    if let Ok(envelope) = serde_json::from_str::<TrustedApprovalKeyCacheEnvelope>(&raw) {
        if !envelope.keys.is_empty() {
            return Ok(TrustedApprovalKeyCache {
                source: envelope.source,
                last_refresh_at: envelope.last_refresh_at,
                keys: envelope.keys,
            });
        }
    }

    if let Ok(envelope) = serde_json::from_str::<TrustedApprovalKeyEnvelope>(&raw) {
        if !envelope.keys.is_empty() {
            return Ok(TrustedApprovalKeyCache {
                source: ApprovalTrustSource::Cached,
                last_refresh_at: None,
                keys: envelope.keys,
            });
        }
    }
    if let Ok(keys) = serde_json::from_str::<Vec<TrustedApprovalKey>>(&raw) {
        if !keys.is_empty() {
            return Ok(TrustedApprovalKeyCache {
                source: ApprovalTrustSource::Cached,
                last_refresh_at: None,
                keys,
            });
        }
    }
    if let Ok(key) = serde_json::from_str::<TrustedApprovalKey>(&raw) {
        return Ok(TrustedApprovalKeyCache {
            source: ApprovalTrustSource::Cached,
            last_refresh_at: None,
            keys: vec![key],
        });
    }

    Err(format!(
        "approval key set {} must be a signing-key json object or array",
        path.display()
    ))
}

/// Load trusted approval signing keys from one or more local cache files.
pub fn load_trusted_approval_key_cache_from_paths(
    paths: &[impl AsRef<Path>],
) -> Result<TrustedApprovalKeyCache, String> {
    if paths.is_empty() {
        return Err("approval key set required for credential verification".to_string());
    }

    let mut last_refresh_at: Option<String> = None;
    let mut keys = Vec::new();
    for path in paths {
        let cache = load_trusted_approval_key_cache_from_file(path.as_ref())?;
        if let Some(refresh_at) = cache.last_refresh_at {
            if last_refresh_at
                .as_ref()
                .map_or(true, |current| refresh_at > *current)
            {
                last_refresh_at = Some(refresh_at);
            }
        }
        keys.extend(cache.keys);
    }

    if keys.is_empty() {
        return Err("approval key set required for credential verification".to_string());
    }

    keys.sort_by(|left, right| left.kid.cmp(&right.kid));
    keys.dedup_by(|left, right| left.kid == right.kid);

    Ok(TrustedApprovalKeyCache {
        source: ApprovalTrustSource::Cached,
        last_refresh_at,
        keys,
    })
}

/// Persist a trusted approval key cache envelope to disk.
pub fn write_trusted_approval_key_cache(
    path: &Path,
    cache: &TrustedApprovalKeyCache,
) -> Result<(), String> {
    let payload = serde_json::to_vec_pretty(&TrustedApprovalKeyCacheEnvelope {
        source: cache.source.clone(),
        last_refresh_at: cache.last_refresh_at.clone(),
        keys: cache.keys.clone(),
    })
    .map_err(|error| format!("serialize approval key set {}: {error}", path.display()))?;
    std::fs::write(path, payload)
        .map_err(|error| format!("write approval key set {}: {error}", path.display()))
}

/// Read approval-refresh bootstrap configuration from the runtime environment.
pub fn approval_refresh_bootstrap_from_env() -> Result<Option<ApprovalRefreshBootstrap>, String> {
    let api_base_url = std::env::var("BYTEOR_API_BASE_URL").ok();
    let agent_id = std::env::var("BYTEOR_AGENT_ID").ok();
    let agent_api_key = std::env::var("BYTEOR_AGENT_API_KEY").ok();

    if api_base_url.is_none() && agent_id.is_none() && agent_api_key.is_none() {
        return Ok(None);
    }

    let mut missing = Vec::new();
    if api_base_url.as_deref().map(str::is_empty).unwrap_or(true) {
        missing.push("BYTEOR_API_BASE_URL");
    }
    if agent_id.as_deref().map(str::is_empty).unwrap_or(true) {
        missing.push("BYTEOR_AGENT_ID");
    }
    if agent_api_key.as_deref().map(str::is_empty).unwrap_or(true) {
        missing.push("BYTEOR_AGENT_API_KEY");
    }
    if !missing.is_empty() {
        return Err(format!(
            "approval refresh bootstrap is incomplete; missing {}",
            missing.join(", ")
        ));
    }

    Ok(Some(ApprovalRefreshBootstrap {
        api_base_url: api_base_url.expect("api base url present"),
        agent_id: agent_id.expect("agent id present"),
        agent_api_key: agent_api_key.expect("agent api key present"),
    }))
}

/// Load trusted approval keys for runtime startup, refreshing from the control plane when possible.
pub fn load_runtime_trusted_approval_key_cache(
    spec_path: &Path,
    configured_paths: &[PathBuf],
    bootstrap: Option<&ApprovalRefreshBootstrap>,
) -> Result<TrustedApprovalKeyCache, String> {
    let local_paths = effective_local_key_paths(spec_path, configured_paths);

    if let Some(bootstrap) = bootstrap {
        match refresh_runtime_trusted_approval_key_cache(spec_path, configured_paths, bootstrap) {
            Ok(cache) => return Ok(cache),
            Err(refresh_error) => {
                return load_trusted_approval_key_cache_from_paths(&local_paths)
                    .map_err(|cache_error| format!("{refresh_error}; {cache_error}"));
            }
        }
    }

    load_trusted_approval_key_cache_from_paths(&local_paths)
}

/// Refresh trusted approval keys from the control plane and persist them into the local runtime cache.
pub fn refresh_runtime_trusted_approval_key_cache(
    spec_path: &Path,
    configured_paths: &[PathBuf],
    bootstrap: &ApprovalRefreshBootstrap,
) -> Result<TrustedApprovalKeyCache, String> {
    let cache_path = runtime_key_cache_write_path(spec_path, configured_paths)
        .ok_or_else(|| "approval key cache path unavailable for runtime startup".to_string())?;
    let refreshed = fetch_trusted_approval_keys_from_control_plane(bootstrap)?;
    write_trusted_approval_key_cache(&cache_path, &refreshed)?;
    Ok(refreshed)
}

/// Derive the approval capabilities required by a canonical spec.
pub fn required_approval_capabilities_for_spec_kv(spec_kv: &str) -> Vec<String> {
    let mut capabilities = Vec::new();
    if spec_kv.contains("http_post:") {
        capabilities.push("http_post".to_string());
    }
    if spec_kv.contains("exec:") {
        capabilities.push("exec".to_string());
    }
    if !capabilities.is_empty() {
        capabilities.push("execute_side_effects".to_string());
    }
    capabilities.sort();
    capabilities.dedup();
    capabilities
}

/// Compute the canonical `sha256:<hex>` digest expected inside approval credentials.
pub fn approval_spec_hash_from_canonical_spec_kv(spec_kv: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(spec_kv.as_bytes());
    format!("sha256:{:x}", hasher.finalize())
}

/// Extract the credential expiry timestamp from an approval credential payload.
pub fn approval_credential_expires_at(credential: &str) -> Result<String, String> {
    let (payload_b64, _) = credential.split_once('.').ok_or_else(|| {
        "approval credential is not formatted as <payload>.<signature>".to_string()
    })?;
    let payload_bytes = URL_SAFE_NO_PAD
        .decode(payload_b64)
        .map_err(|_| "approval credential payload is not valid base64url".to_string())?;
    let payload: ApprovalCredentialPayload = serde_json::from_slice(&payload_bytes)
        .map_err(|_| "approval credential payload is not valid json".to_string())?;
    Ok(payload.expires_at)
}

fn environment_posture(env: Environment) -> &'static str {
    match env {
        Environment::Dev => "dev",
        Environment::Staging => "staging",
        Environment::Prod => "prod",
    }
}

fn verify_approval_credential(
    credential: &str,
    trusted_keys: &[TrustedApprovalKey],
    spec_hash: &str,
    environment_posture: &str,
    required_capabilities: &[String],
) -> Result<(), ApprovalVerificationError> {
    if trusted_keys.is_empty() {
        return Err(ApprovalVerificationError::MissingKeySet);
    }

    let (payload_b64, signature_b64) = credential
        .split_once('.')
        .ok_or(ApprovalVerificationError::InvalidFormat)?;
    let payload_bytes = URL_SAFE_NO_PAD
        .decode(payload_b64)
        .map_err(|_| ApprovalVerificationError::InvalidBase64)?;
    let signature_bytes = URL_SAFE_NO_PAD
        .decode(signature_b64)
        .map_err(|_| ApprovalVerificationError::InvalidBase64)?;
    let payload: ApprovalCredentialPayload = serde_json::from_slice(&payload_bytes)
        .map_err(|_| ApprovalVerificationError::InvalidPayloadJson)?;

    if payload.v != 1 {
        return Err(ApprovalVerificationError::UnsupportedVersion(payload.v));
    }

    let trusted_key = trusted_keys
        .iter()
        .find(|key| key.kid == payload.kid)
        .ok_or_else(|| ApprovalVerificationError::UnknownKeyId(payload.kid.clone()))?;
    if trusted_key.algorithm != "Ed25519" {
        return Err(ApprovalVerificationError::UnsupportedAlgorithm(
            trusted_key.algorithm.clone(),
        ));
    }

    let verifying_key = parse_verifying_key_from_pem(&trusted_key.public_key_pem)
        .map_err(|_| ApprovalVerificationError::InvalidPublicKeyPem(trusted_key.kid.clone()))?;
    let signature = Signature::try_from(signature_bytes.as_slice())
        .map_err(|_| ApprovalVerificationError::InvalidSignature)?;
    verifying_key
        .verify(&payload_bytes, &signature)
        .map_err(|_| ApprovalVerificationError::InvalidSignature)?;

    if payload.spec_hash != spec_hash {
        return Err(ApprovalVerificationError::SpecHashMismatch);
    }
    if payload.environment_posture != environment_posture {
        return Err(ApprovalVerificationError::EnvironmentMismatch);
    }

    let expires_at = OffsetDateTime::parse(payload.expires_at.as_str(), &Rfc3339)
        .map_err(|_| ApprovalVerificationError::InvalidPayloadJson)?;
    if OffsetDateTime::now_utc() >= expires_at {
        return Err(ApprovalVerificationError::Expired);
    }

    let missing_capabilities = required_capabilities
        .iter()
        .filter(|capability| !payload.capabilities.contains(*capability))
        .cloned()
        .collect::<Vec<_>>();
    if !missing_capabilities.is_empty() {
        return Err(ApprovalVerificationError::InsufficientCapabilities(
            missing_capabilities,
        ));
    }

    Ok(())
}

fn parse_verifying_key_from_pem(pem: &str) -> Result<VerifyingKey, ()> {
    let der_bytes = pem
        .lines()
        .filter(|line| !line.starts_with("-----"))
        .collect::<String>();
    let der = base64::engine::general_purpose::STANDARD
        .decode(der_bytes.as_bytes())
        .map_err(|_| ())?;
    let public_key_bytes: [u8; 32] = der
        .get(der.len().saturating_sub(32)..)
        .ok_or(())?
        .try_into()
        .map_err(|_| ())?;
    VerifyingKey::from_bytes(&public_key_bytes).map_err(|_| ())
}

fn effective_local_key_paths(spec_path: &Path, configured_paths: &[PathBuf]) -> Vec<PathBuf> {
    if configured_paths.is_empty() {
        discover_trusted_approval_key_paths(spec_path)
    } else {
        configured_paths.to_vec()
    }
}

fn runtime_key_cache_write_path(spec_path: &Path, configured_paths: &[PathBuf]) -> Option<PathBuf> {
    if configured_paths.is_empty() {
        default_trusted_approval_key_cache_path(spec_path)
    } else {
        configured_paths.first().cloned()
    }
}

fn fetch_trusted_approval_keys_from_control_plane(
    bootstrap: &ApprovalRefreshBootstrap,
) -> Result<TrustedApprovalKeyCache, String> {
    let url = format!(
        "{}/api/v1/agents/{}/signing-keys",
        bootstrap.api_base_url.trim_end_matches('/'),
        bootstrap.agent_id
    );
    let response = ureq::AgentBuilder::new()
        .timeout(Duration::from_secs(10))
        .build()
        .get(&url)
        .set(
            "authorization",
            &format!("Bearer {}", bootstrap.agent_api_key),
        )
        .set("accept", "application/json")
        .set("user-agent", "byteor-runtime/0 (api/v1)")
        .call()
        .map_err(|error| format!("refresh approval key set from {url}: {error}"))?;

    let envelope: SigningKeysResponseEnvelope = response
        .into_json()
        .map_err(|error| format!("decode approval key set from {url}: {error}"))?;
    if envelope.data.keys.is_empty() {
        return Err(format!(
            "refresh approval key set from {url}: empty key set"
        ));
    }

    let last_refresh_at = OffsetDateTime::now_utc()
        .format(&Rfc3339)
        .map_err(|error| format!("format approval key refresh timestamp: {error}"))?;

    Ok(TrustedApprovalKeyCache {
        source: ApprovalTrustSource::Refreshed,
        last_refresh_at: Some(last_refresh_at),
        keys: envelope.data.keys,
    })
}

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

    use base64::engine::general_purpose::URL_SAFE_NO_PAD;
    use ed25519_dalek::{pkcs8::EncodePublicKey, Signer as _, SigningKey};
    use serde_json::json;
    use std::fs;
    use std::io::{Read, Write};
    use std::net::TcpListener;

    fn test_signing_key() -> SigningKey {
        SigningKey::from_bytes(&[0x24; 32])
    }

    fn trusted_key() -> TrustedApprovalKey {
        let signing_key = test_signing_key();
        let public_key_pem = signing_key
            .verifying_key()
            .to_public_key_pem(Default::default())
            .expect("public key pem");
        TrustedApprovalKey {
            kid: "01JKEY000TEST0000000000000".to_string(),
            algorithm: "Ed25519".to_string(),
            public_key_pem,
        }
    }

    fn sign_payload(payload: serde_json::Value) -> String {
        let signing_key = test_signing_key();
        let payload = serde_json::to_vec(&payload).expect("payload json");
        let signature = signing_key.sign(&payload);
        format!(
            "{}.{}",
            URL_SAFE_NO_PAD.encode(payload),
            URL_SAFE_NO_PAD.encode(signature.to_bytes())
        )
    }

    fn sign_credential(spec_hash: &str, capabilities: &[&str], posture: &str) -> String {
        sign_payload(json!({
            "v": 1,
            "kid": "01JKEY000TEST0000000000000",
            "approval_id": "01JAPR000TEST0000000000000",
            "org_id": "01JORG000TEST0000000000000",
            "project_id": "01JPROJ00TEST000000000000",
            "environment_id": "01JENV000TEST000000000000",
            "environment_posture": posture,
            "spec_hash": spec_hash,
            "capabilities": capabilities,
            "issued_by": "01JUSER00TEST000000000000",
            "issued_at": "2026-03-20T14:32:00Z",
            "expires_at": "2099-03-21T14:32:00Z"
        }))
    }

    #[test]
    fn resolves_verified_runtime_approval() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential =
            sign_credential(&spec_hash, &["execute_side_effects", "http_post"], "prod");

        let resolution = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect("verified approval");

        assert!(resolution.approval_token_present);
        assert_eq!(resolution.spec_hash, spec_hash);
        assert_eq!(
            resolution.required_capabilities,
            vec!["execute_side_effects".to_string(), "http_post".to_string()]
        );
    }

    #[test]
    fn rejects_untrusted_or_incomplete_credential() {
        let spec_kv = "stage=exec:/usr/bin/true\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential = sign_credential(&spec_hash, &["execute_side_effects"], "prod");

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert!(matches!(
            error,
            ApprovalVerificationError::InsufficientCapabilities(_)
        ));
    }

    #[test]
    fn rejects_approval_with_unknown_key_id() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential = sign_payload(json!({
            "v": 1,
            "kid": "01JKEY000UNKNOWN0000000000",
            "approval_id": "01JAPR000TEST0000000000000",
            "org_id": "01JORG000TEST0000000000000",
            "project_id": "01JPROJ00TEST000000000000",
            "environment_id": "01JENV000TEST000000000000",
            "environment_posture": "prod",
            "spec_hash": spec_hash,
            "capabilities": ["execute_side_effects", "http_post"],
            "issued_by": "01JUSER00TEST000000000000",
            "issued_at": "2026-03-20T14:32:00Z",
            "expires_at": "2099-03-21T14:32:00Z"
        }));

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert!(matches!(
            error,
            ApprovalVerificationError::UnknownKeyId(ref kid)
                if kid == "01JKEY000UNKNOWN0000000000"
        ));
    }

    #[test]
    fn rejects_approval_with_spec_hash_mismatch() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let credential = sign_credential(
            "sha256:deadbeef",
            &["execute_side_effects", "http_post"],
            "prod",
        );

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert_eq!(error, ApprovalVerificationError::SpecHashMismatch);
    }

    #[test]
    fn rejects_approval_with_environment_mismatch() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential = sign_credential(&spec_hash, &["execute_side_effects", "http_post"], "staging");

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert_eq!(error, ApprovalVerificationError::EnvironmentMismatch);
    }

    #[test]
    fn rejects_expired_approval_credential() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential = sign_payload(json!({
            "v": 1,
            "kid": "01JKEY000TEST0000000000000",
            "approval_id": "01JAPR000TEST0000000000000",
            "org_id": "01JORG000TEST0000000000000",
            "project_id": "01JPROJ00TEST000000000000",
            "environment_id": "01JENV000TEST000000000000",
            "environment_posture": "prod",
            "spec_hash": spec_hash,
            "capabilities": ["execute_side_effects", "http_post"],
            "issued_by": "01JUSER00TEST000000000000",
            "issued_at": "2026-03-20T14:32:00Z",
            "expires_at": "2020-03-21T14:32:00Z"
        }));

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert_eq!(error, ApprovalVerificationError::Expired);
    }

    #[test]
    fn rejects_approval_with_invalid_signature() {
        let spec_kv = "stage=http_post:https://example.com\n";
        let spec_hash = approval_spec_hash_from_canonical_spec_kv(spec_kv);
        let credential = sign_credential(&spec_hash, &["execute_side_effects", "http_post"], "prod");
        let (payload_b64, signature_b64) = credential.split_once('.').expect("credential parts");
        let mut payload: serde_json::Value = serde_json::from_slice(
            &URL_SAFE_NO_PAD.decode(payload_b64).expect("decode payload"),
        )
        .expect("payload json");
        payload["environment_posture"] = json!("staging");
        let tampered_payload = serde_json::to_vec(&payload).expect("tampered payload json");
        let tampered_credential = format!(
            "{}.{}",
            URL_SAFE_NO_PAD.encode(tampered_payload),
            signature_b64
        );

        let error = resolve_runtime_approval(
            spec_kv,
            Environment::Prod,
            Some(tampered_credential.as_str()),
            &[trusted_key()],
        )
        .expect_err("credential should be rejected");

        assert_eq!(error, ApprovalVerificationError::InvalidSignature);
    }

    #[test]
    fn reads_and_writes_trusted_key_cache_metadata() {
        let temp_dir = std::env::temp_dir().join(format!(
            "byteor-approval-cache-{}",
            OffsetDateTime::now_utc().unix_timestamp_nanos()
        ));
        fs::create_dir_all(&temp_dir).expect("temp dir");
        let cache_path = temp_dir.join("signing_keys.json");
        let cache = TrustedApprovalKeyCache {
            source: ApprovalTrustSource::Refreshed,
            last_refresh_at: Some("2026-03-20T14:35:00Z".to_string()),
            keys: vec![trusted_key()],
        };

        write_trusted_approval_key_cache(&cache_path, &cache).expect("write cache");
        let loaded = load_trusted_approval_key_cache_from_file(&cache_path).expect("load cache");

        assert_eq!(loaded.source, ApprovalTrustSource::Refreshed);
        assert_eq!(
            loaded.last_refresh_at.as_deref(),
            Some("2026-03-20T14:35:00Z")
        );
        assert_eq!(loaded.keys.len(), 1);

        fs::remove_dir_all(&temp_dir).ok();
    }

    #[test]
    fn refreshes_trusted_keys_from_control_plane_and_persists_cache() {
        let temp_dir = std::env::temp_dir().join(format!(
            "byteor-approval-refresh-{}",
            OffsetDateTime::now_utc().unix_timestamp_nanos()
        ));
        fs::create_dir_all(&temp_dir).expect("temp dir");
        let spec_path = temp_dir.join("spec.kv");
        fs::write(&spec_path, "stage=http_post:https://example.com\n").expect("write spec");

        let listener = TcpListener::bind("127.0.0.1:0").expect("bind listener");
        let addr = listener.local_addr().expect("listener addr");
        let response_key = trusted_key();
        let response_body = serde_json::to_string(&json!({
            "data": {
                "keys": [response_key]
            }
        }))
        .expect("response json");

        let server = std::thread::spawn(move || {
            let (mut stream, _) = listener.accept().expect("accept connection");
            let mut request = [0_u8; 4096];
            let bytes_read = stream.read(&mut request).expect("read request");
            let request_text = String::from_utf8_lossy(&request[..bytes_read]);
            assert!(request_text.contains("GET /api/v1/agents/01JAGENTTEST/signing-keys HTTP/1.1"));
            assert!(request_text.contains("authorization: Bearer byteor_ak_test"));

            let response = format!(
                "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
                response_body.len(),
                response_body
            );
            stream
                .write_all(response.as_bytes())
                .expect("write response");
        });

        let bootstrap = ApprovalRefreshBootstrap {
            api_base_url: format!("http://{addr}"),
            agent_id: "01JAGENTTEST".to_string(),
            agent_api_key: "byteor_ak_test".to_string(),
        };

        let cache = refresh_runtime_trusted_approval_key_cache(&spec_path, &[], &bootstrap)
            .expect("refresh cache");

        assert_eq!(cache.source, ApprovalTrustSource::Refreshed);
        assert!(cache.last_refresh_at.is_some());
        assert_eq!(cache.keys.len(), 1);

        let persisted =
            load_trusted_approval_key_cache_from_file(&temp_dir.join("signing_keys.json"))
                .expect("load persisted cache");
        assert_eq!(persisted.source, ApprovalTrustSource::Refreshed);
        assert_eq!(persisted.keys.len(), 1);

        server.join().expect("server thread");
        fs::remove_dir_all(&temp_dir).ok();
    }

    #[test]
    fn falls_back_to_cached_keys_when_online_refresh_fails() {
        let temp_dir = std::env::temp_dir().join(format!(
            "byteor-approval-refresh-fallback-{}",
            OffsetDateTime::now_utc().unix_timestamp_nanos()
        ));
        fs::create_dir_all(&temp_dir).expect("temp dir");
        let spec_path = temp_dir.join("spec.kv");
        fs::write(&spec_path, "stage=http_post:https://example.com\n").expect("write spec");
        write_trusted_approval_key_cache(
            &temp_dir.join("signing_keys.json"),
            &TrustedApprovalKeyCache {
                source: ApprovalTrustSource::Refreshed,
                last_refresh_at: Some("2026-03-20T14:35:00Z".to_string()),
                keys: vec![trusted_key()],
            },
        )
        .expect("write cached key set");

        let listener = TcpListener::bind("127.0.0.1:0").expect("bind listener");
        let addr = listener.local_addr().expect("listener addr");
        let server = std::thread::spawn(move || {
            let (mut stream, _) = listener.accept().expect("accept connection");
            let mut request = [0_u8; 2048];
            let _ = stream.read(&mut request).expect("read request");
            stream
                .write_all(
                    b"HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
                )
                .expect("write response");
        });

        let bootstrap = ApprovalRefreshBootstrap {
            api_base_url: format!("http://{addr}"),
            agent_id: "01JAGENTTEST".to_string(),
            agent_api_key: "byteor_ak_test".to_string(),
        };

        let cache = load_runtime_trusted_approval_key_cache(&spec_path, &[], Some(&bootstrap))
            .expect("load cached fallback");

        assert_eq!(cache.source, ApprovalTrustSource::Cached);
        assert_eq!(
            cache.last_refresh_at.as_deref(),
            Some("2026-03-20T14:35:00Z")
        );
        assert_eq!(cache.keys.len(), 1);

        server.join().expect("server thread");
        fs::remove_dir_all(&temp_dir).ok();
    }
}