ahri_tre_secrets/

lib.rs

//! Canonical Secret references and Secret resolution infrastructure.

mod acquisition;
mod managed;
pub use acquisition::{SourceCredentialError, SourceCredentials};

use age::x25519;

pub use managed::{
    LocalManagedSecretStore, MANAGED_SECRET_ROOT, MANAGED_SECRET_ROTATION_ROOT,
    ManagedSecretBackend, ManagedSecretError, ManagedSecretErrorKind, ManagedSecretIdentity,
    ManagedSecretMetadata, ManagedSecretVerification, ManagedSecretVersion,
    NEXT_ROOT_IDENTITY_PATH, ROOT_IDENTITY_PATH, ResolvedManagedSecret, RootRotationError,
    RootRotationPhase, RootRotationVerification, SelectedManagedSecretReader,
};

/// Repository-internal Trusted-runtime capability surface.
#[doc(hidden)]
pub mod internal {
    pub use super::managed::{
        ManagedSecretOwnerBackend, ManagedSecretReferenceAuthorities,
        ManagedSecretReferenceAuthority, ManagedSecretReferenceAuthorityKind,
        ManagedSecretReferenceInspectionError, ManagedSecretReferenceStatus,
        ManagedSecretRemovalProof, ManagedSecretRemovalProofError,
        ManagedSecretRemovalProofErrorKind, ManagedSecretTrustedBackend, StagedManagedSecret,
    };
}

#[cfg(target_os = "linux")]
use rustix::fs::{Mode, OFlags, ResolveFlags, openat2};
use secrecy::{ExposeSecret, SecretSlice, zeroize::Zeroize};
use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
use std::collections::{BTreeMap, BTreeSet};
use std::fmt;
use std::fs::{self, File, OpenOptions};
#[cfg(target_os = "linux")]
use std::io::Read;
use std::io::Write;
#[cfg(target_os = "linux")]
use std::os::fd::AsRawFd;
#[cfg(unix)]
use std::os::unix::fs::{MetadataExt, OpenOptionsExt, PermissionsExt};
use std::path::{Path, PathBuf};
use std::str::FromStr;
use thiserror::Error;

/// Maximum encoded length of a canonical Secret reference.
pub const MAX_SECRET_REFERENCE_BYTES: usize = 512;
/// Maximum logical value size for either Secret tier.
pub const MAX_SECRET_MATERIAL_BYTES: usize = 64 * 1024;
/// Fixed production root for externally projected Injected secrets.
pub const INJECTED_SECRET_ROOT: &str = "/run/secrets";

const MANAGED_SCHEME: &str = "managed://";
const INJECTED_SCHEME: &str = "injected://";

/// The storage tier named by a canonical Secret reference.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum SecretTier {
    Managed,
    Injected,
}

/// A bounded canonical logical Secret reference.
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct SecretReference {
    canonical: Box<str>,
    tier: SecretTier,
}

impl SecretReference {
    pub fn as_str(&self) -> &str {
        &self.canonical
    }

    pub fn tier(&self) -> SecretTier {
        self.tier
    }

    pub fn segments(&self) -> impl Iterator<Item = &str> {
        self.path().split('/')
    }

    fn path(&self) -> &str {
        match self.tier {
            SecretTier::Managed => &self.canonical[MANAGED_SCHEME.len()..],
            SecretTier::Injected => &self.canonical[INJECTED_SCHEME.len()..],
        }
    }
}

impl fmt::Debug for SecretReference {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_tuple("SecretReference")
            .field(&self.canonical)
            .finish()
    }
}

impl fmt::Display for SecretReference {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.canonical)
    }
}

impl FromStr for SecretReference {
    type Err = SecretReferenceParseError;

    fn from_str(input: &str) -> Result<Self, Self::Err> {
        parse_reference(input)
    }
}

impl Serialize for SecretReference {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for SecretReference {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let input = <&str>::deserialize(deserializer)?;
        Self::from_str(input).map_err(de::Error::custom)
    }
}

/// A canonical reference to the encrypted Managed-secret tier.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
#[serde(transparent)]
pub struct ManagedSecretReference(SecretReference);

impl ManagedSecretReference {
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }

    pub fn as_secret_reference(&self) -> &SecretReference {
        &self.0
    }
}

impl fmt::Display for ManagedSecretReference {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(formatter)
    }
}

impl FromStr for ManagedSecretReference {
    type Err = SecretReferenceParseError;

    fn from_str(input: &str) -> Result<Self, Self::Err> {
        let reference = SecretReference::from_str(input)?;
        if reference.tier() != SecretTier::Managed {
            return Err(SecretReferenceParseError::WrongTier);
        }
        Ok(Self(reference))
    }
}

impl<'de> Deserialize<'de> for ManagedSecretReference {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let input = <&str>::deserialize(deserializer)?;
        Self::from_str(input).map_err(de::Error::custom)
    }
}

/// A canonical reference to the externally projected Injected-secret tier.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
#[serde(transparent)]
pub struct InjectedSecretReference(SecretReference);

impl InjectedSecretReference {
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }

    pub fn as_secret_reference(&self) -> &SecretReference {
        &self.0
    }

    pub fn segments(&self) -> impl Iterator<Item = &str> {
        self.0.segments()
    }
}

impl fmt::Display for InjectedSecretReference {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(formatter)
    }
}

impl FromStr for InjectedSecretReference {
    type Err = SecretReferenceParseError;

    fn from_str(input: &str) -> Result<Self, Self::Err> {
        let reference = SecretReference::from_str(input)?;
        if reference.tier() != SecretTier::Injected {
            return Err(SecretReferenceParseError::WrongTier);
        }
        Ok(Self(reference))
    }
}

impl<'de> Deserialize<'de> for InjectedSecretReference {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let input = <&str>::deserialize(deserializer)?;
        Self::from_str(input).map_err(de::Error::custom)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
pub enum SecretReferenceParseError {
    #[error("Secret reference uses an unsupported or non-canonical scheme")]
    InvalidScheme,
    #[error("Secret reference exceeds the maximum encoded length")]
    TooLong,
    #[error("Secret reference must contain between one and eight segments")]
    InvalidSegmentCount,
    #[error("Secret reference contains a non-canonical segment")]
    InvalidSegment,
    #[error("Secret reference names the wrong Secret tier")]
    WrongTier,
}

fn parse_reference(input: &str) -> Result<SecretReference, SecretReferenceParseError> {
    if input.len() > MAX_SECRET_REFERENCE_BYTES {
        return Err(SecretReferenceParseError::TooLong);
    }

    let (tier, path) = if let Some(path) = input.strip_prefix(MANAGED_SCHEME) {
        (SecretTier::Managed, path)
    } else if let Some(path) = input.strip_prefix(INJECTED_SCHEME) {
        (SecretTier::Injected, path)
    } else {
        return Err(SecretReferenceParseError::InvalidScheme);
    };

    let segments = path.split('/').collect::<Vec<_>>();
    if !(1..=8).contains(&segments.len()) {
        return Err(SecretReferenceParseError::InvalidSegmentCount);
    }
    if segments.iter().any(|segment| !valid_segment(segment)) {
        return Err(SecretReferenceParseError::InvalidSegment);
    }

    Ok(SecretReference {
        canonical: input.into(),
        tier,
    })
}

fn valid_segment(segment: &str) -> bool {
    if segment.is_empty() || segment.len() > 63 {
        return false;
    }
    let bytes = segment.as_bytes();
    if !bytes.first().is_some_and(u8::is_ascii_alphanumeric)
        || !bytes.last().is_some_and(u8::is_ascii_alphanumeric)
    {
        return false;
    }

    let mut previous_hyphen = false;
    for byte in bytes {
        match byte {
            b'a'..=b'z' | b'0'..=b'9' => previous_hyphen = false,
            b'-' if !previous_hyphen => previous_hyphen = true,
            _ => return false,
        }
    }
    true
}

/// An exact externally supplied version label for an Injected secret.
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
#[serde(transparent)]
pub struct InjectedSecretVersion(Box<str>);

impl InjectedSecretVersion {
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Debug for InjectedSecretVersion {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_tuple("InjectedSecretVersion")
            .field(&self.0)
            .finish()
    }
}

impl fmt::Display for InjectedSecretVersion {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.0)
    }
}

impl FromStr for InjectedSecretVersion {
    type Err = InjectedSecretVersionParseError;

    fn from_str(input: &str) -> Result<Self, Self::Err> {
        if input.is_empty() || input.len() > 64 {
            return Err(InjectedSecretVersionParseError);
        }
        let bytes = input.as_bytes();
        if !bytes.first().is_some_and(u8::is_ascii_alphanumeric)
            || !bytes.last().is_some_and(u8::is_ascii_alphanumeric)
        {
            return Err(InjectedSecretVersionParseError);
        }

        let mut previous_separator = false;
        for byte in bytes {
            match byte {
                b'a'..=b'z' | b'0'..=b'9' => previous_separator = false,
                b'.' | b'_' | b'-' if !previous_separator => previous_separator = true,
                _ => return Err(InjectedSecretVersionParseError),
            }
        }
        Ok(Self(input.into()))
    }
}

impl<'de> Deserialize<'de> for InjectedSecretVersion {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let input = <&str>::deserialize(deserializer)?;
        Self::from_str(input).map_err(de::Error::custom)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("Injected-secret version label is not canonical")]
pub struct InjectedSecretVersionParseError;

/// Bounded Secret bytes protected from accidental formatting or serialization.
///
/// Access is deliberately scoped to a closure, and ordinary Serde output is not
/// implemented:
///
/// ```compile_fail
/// let material = ahri_tre_secrets::SecretMaterial::try_from(b"secret".to_vec()).unwrap();
/// let _ = serde_json::to_string(&material);
/// ```
pub struct SecretMaterial(SecretSlice<u8>);

impl SecretMaterial {
    pub fn expose<R>(&self, use_material: impl FnOnce(&[u8]) -> R) -> R {
        use_material(self.0.expose_secret())
    }
}

/// Generates deployment-local bootstrap material without exposing raw Secret
/// ownership to configuration or runtime crates.
pub fn generate_local_foundation_secret() -> SecretMaterial {
    let material = format!(
        "{}{}",
        uuid::Uuid::new_v4().simple(),
        uuid::Uuid::new_v4().simple()
    )
    .into_bytes();
    SecretMaterial::try_from(material).expect("UUID bootstrap material is bounded")
}

/// A fixed private provider artifact owned by the Local deployment foundation.
///
/// Keeping the path selection in this crate prevents the provisioner from
/// becoming a second, general-purpose Secret-file writer.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LocalProviderCredential {
    CertificateAuthorityPrivateKey,
    RuntimeTlsPrivateKey,
    WebTlsPrivateKey,
    PostgresTlsPrivateKey,
    PostgresInternalTlsPrivateKey,
    BrowserTlsPrivateKey,
    OidcIdentityPassword,
    OidcIdentityArchive,
    OidcSigningPrivateKey,
    OidcClientSecret,
    DiagnosticPassword,
}

impl LocalProviderCredential {
    fn path(self) -> &'static Path {
        Path::new(match self {
            Self::CertificateAuthorityPrivateKey => "/var/lib/postgresql/trust/ca.key",
            Self::RuntimeTlsPrivateKey => "/var/lib/postgresql/trust/runtime.key",
            Self::WebTlsPrivateKey => "/var/lib/postgresql/trust/web.key",
            Self::PostgresTlsPrivateKey => "/run/postgres-tls/postgres.key",
            Self::PostgresInternalTlsPrivateKey => {
                "/var/lib/postgresql/trust/postgres-internal.key"
            }
            Self::BrowserTlsPrivateKey => "/run/browser-tls/browser.key",
            Self::OidcIdentityPassword => "/run/oidc/identity-password",
            Self::OidcIdentityArchive => "/run/oidc/identity.p12",
            Self::OidcSigningPrivateKey => "/run/oidc/signing-key.pem",
            Self::OidcClientSecret => "/run/oidc/client-secret",
            Self::DiagnosticPassword => "/run/diagnostic-input/password",
        })
    }
}

/// Creates one allow-listed Local provider credential with protected initial
/// permissions. Existing state is never replaced.
pub fn initialize_local_provider_credential(
    target: LocalProviderCredential,
    material: &SecretMaterial,
) -> Result<(), LocalProviderCredentialError> {
    write_new_local_provider_credential(target.path(), material)
}

/// Generates and creates the fixed, short-lived Local database-diagnostic
/// password export without returning its material to deployment shell code.
pub fn initialize_local_diagnostic_password() -> Result<(), LocalProviderCredentialError> {
    let value = format!(
        "diagnostic-{}{}",
        uuid::Uuid::new_v4().simple(),
        uuid::Uuid::new_v4().simple()
    );
    let material =
        SecretMaterial::try_from(value.into_bytes()).map_err(|_| LocalProviderCredentialError)?;
    initialize_local_provider_credential(LocalProviderCredential::DiagnosticPassword, &material)
}

/// Replaces only PostgreSQL's temporary Local diagnostic TLS credential.
/// The broad foundation writer remains create-only; this narrower lifecycle
/// capability exists solely for explicit diagnostic expose/revoke.
pub fn replace_local_postgres_tls_credential_for_diagnostic(
    material: &SecretMaterial,
) -> Result<(), LocalProviderCredentialError> {
    replace_local_provider_credential(
        LocalProviderCredential::PostgresTlsPrivateKey.path(),
        material,
    )
}

fn replace_local_provider_credential(
    path: &Path,
    material: &SecretMaterial,
) -> Result<(), LocalProviderCredentialError> {
    let metadata = fs::symlink_metadata(path).map_err(|_| LocalProviderCredentialError)?;
    #[cfg(unix)]
    {
        // SAFETY: geteuid has no preconditions and retains no pointers.
        let effective_uid = unsafe { libc::geteuid() };
        if !metadata.is_file()
            || metadata.file_type().is_symlink()
            || metadata.uid() != effective_uid
            || metadata.permissions().mode() & 0o777 != 0o400
            || metadata.nlink() != 1
        {
            return Err(LocalProviderCredentialError);
        }
    }
    let parent = path.parent().ok_or(LocalProviderCredentialError)?;
    let staged = parent.join(format!(".provider-{}.tmp", uuid::Uuid::new_v4()));
    if let Err(error) = write_new_local_provider_credential(&staged, material) {
        let _ = fs::remove_file(&staged);
        return Err(error);
    }
    if fs::rename(&staged, path).is_err() {
        let _ = fs::remove_file(&staged);
        return Err(LocalProviderCredentialError);
    }
    File::open(parent)
        .and_then(|directory| directory.sync_all())
        .map_err(|_| LocalProviderCredentialError)
}

fn write_new_local_provider_credential(
    path: &Path,
    material: &SecretMaterial,
) -> Result<(), LocalProviderCredentialError> {
    let parent = path.parent().ok_or(LocalProviderCredentialError)?;
    let metadata = fs::symlink_metadata(parent).map_err(|_| LocalProviderCredentialError)?;
    if !metadata.is_dir() || metadata.file_type().is_symlink() {
        return Err(LocalProviderCredentialError);
    }
    #[cfg(unix)]
    {
        // SAFETY: geteuid has no preconditions and retains no pointers.
        let effective_uid = unsafe { libc::geteuid() };
        if metadata.uid() != effective_uid || metadata.permissions().mode() & 0o077 != 0 {
            return Err(LocalProviderCredentialError);
        }
    }
    let mut options = OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    options.mode(0o400);
    let mut file = options
        .open(path)
        .map_err(|_| LocalProviderCredentialError)?;
    material
        .expose(|bytes| file.write_all(bytes))
        .and_then(|_| file.sync_all())
        .map_err(|_| LocalProviderCredentialError)
}

/// Path-free failure while creating an allow-listed Local provider credential.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("Local provider credential could not be initialized")]
pub struct LocalProviderCredentialError;

/// Path-free failure while creating Local root-identity authority.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("Local root identity could not be initialized")]
pub struct LocalRootIdentityProvisionError;

/// Generates and projects a new Local root identity, then initializes the
/// Deployment-bound Managed store without returning identity material.
pub fn initialize_local_foundation_managed_store(
    deployment_id: uuid::Uuid,
) -> Result<(), LocalRootIdentityProvisionError> {
    let identity = x25519::Identity::generate().to_string();
    let material = SecretMaterial::try_from(identity.expose_secret().as_bytes().to_vec())
        .map_err(|_| LocalRootIdentityProvisionError)?;
    let reference = InjectedSecretReference::from_str("injected://ahri-tre/root-identity")
        .map_err(|_| LocalRootIdentityProvisionError)?;
    let version =
        InjectedSecretVersion::from_str("local-v1").map_err(|_| LocalRootIdentityProvisionError)?;
    initialize_injected_projection_for_local_foundation(
        Path::new(INJECTED_SECRET_ROOT),
        &reference,
        &version,
        &material,
    )
    .map_err(|_| LocalRootIdentityProvisionError)?;
    let identity = ManagedSecretIdentity::from_material(&material)
        .map_err(|_| LocalRootIdentityProvisionError)?;
    LocalManagedSecretStore::initialize(deployment_id, identity)
        .map_err(|_| LocalRootIdentityProvisionError)?;
    Ok(())
}

/// Creates the distinct next-root projection consumed only by the stopped
/// offline rotation workload. Existing next-root state is never replaced.
pub fn initialize_local_foundation_next_root_identity()
-> Result<(), LocalRootIdentityProvisionError> {
    let identity = x25519::Identity::generate().to_string();
    let material = SecretMaterial::try_from(identity.expose_secret().as_bytes().to_vec())
        .map_err(|_| LocalRootIdentityProvisionError)?;
    let reference = InjectedSecretReference::from_str("injected://ahri-tre/root-identity-next")
        .map_err(|_| LocalRootIdentityProvisionError)?;
    let version = InjectedSecretVersion::from_str("local-rotation-v1")
        .map_err(|_| LocalRootIdentityProvisionError)?;
    initialize_injected_projection_for_local_foundation(
        Path::new(INJECTED_SECRET_ROOT),
        &reference,
        &version,
        &material,
    )
    .map_err(|_| LocalRootIdentityProvisionError)
}

impl TryFrom<Vec<u8>> for SecretMaterial {
    type Error = SecretMaterialError;

    fn try_from(mut value: Vec<u8>) -> Result<Self, Self::Error> {
        if value.len() > MAX_SECRET_MATERIAL_BYTES {
            value.zeroize();
            return Err(SecretMaterialError::TooLarge);
        }
        Ok(Self(value.into()))
    }
}

impl fmt::Debug for SecretMaterial {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_tuple("SecretMaterial")
            .field(&ahri_tre_security::REDACTED_VALUE)
            .finish()
    }
}

/// Writes one new Local-deployment Injected-secret projection without exposing
/// the projection layout to the provisioner. The caller owns the selected
/// deployment volume; a projection is never replaced in place.
pub fn initialize_injected_projection_for_local_foundation(
    root: &Path,
    reference: &InjectedSecretReference,
    version: &InjectedSecretVersion,
    material: &SecretMaterial,
) -> Result<(), InjectedSecretProvisionError> {
    fs::create_dir_all(root).map_err(|_| InjectedSecretProvisionError)?;
    set_private_directory_mode(root)?;
    let directory = reference
        .segments()
        .fold(root.to_path_buf(), |path, segment| path.join(segment));
    fs::create_dir_all(&directory).map_err(|_| InjectedSecretProvisionError)?;
    set_private_directory_mode(&directory)?;
    write_new_private_projection_file(&directory.join("value"), material)?;
    write_new_version_projection_file(&directory.join("version"), version)?;
    Ok(())
}

/// Replaces one explicitly temporary Local acceptance projection before its
/// consuming workload starts. The reference owns a complete leaf directory;
/// failure leaves that capability absent rather than retaining stale material.
pub fn replace_injected_projection_for_local_acceptance(
    root: &Path,
    reference: &InjectedSecretReference,
    version: &InjectedSecretVersion,
    material: &SecretMaterial,
) -> Result<(), InjectedSecretProvisionError> {
    remove_injected_projection_for_local_acceptance(root, reference)?;
    initialize_injected_projection_for_local_foundation(root, reference, version, material)
}

/// Removes one temporary Local acceptance projection without traversing or
/// changing any sibling capability.
pub fn remove_injected_projection_for_local_acceptance(
    root: &Path,
    reference: &InjectedSecretReference,
) -> Result<(), InjectedSecretProvisionError> {
    let mut directory = root.to_path_buf();
    for segment in reference.segments() {
        let metadata = match fs::symlink_metadata(&directory) {
            Ok(metadata) => metadata,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
            Err(_) => return Err(InjectedSecretProvisionError),
        };
        if metadata.file_type().is_symlink() || !metadata.is_dir() {
            return Err(InjectedSecretProvisionError);
        }
        directory.push(segment);
    }
    if let Ok(metadata) = fs::symlink_metadata(&directory)
        && metadata.file_type().is_symlink()
    {
        return Err(InjectedSecretProvisionError);
    }
    match fs::remove_dir_all(&directory) {
        Ok(()) => Ok(()),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(_) => Err(InjectedSecretProvisionError),
    }
}

fn write_new_private_projection_file(
    path: &Path,
    material: &SecretMaterial,
) -> Result<(), InjectedSecretProvisionError> {
    let mut options = OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    options.mode(0o400);
    let mut file = options
        .open(path)
        .map_err(|_| InjectedSecretProvisionError)?;
    material
        .expose(|bytes| file.write_all(bytes))
        .map_err(|_| InjectedSecretProvisionError)?;
    file.sync_all().map_err(|_| InjectedSecretProvisionError)?;
    Ok(())
}

fn write_new_version_projection_file(
    path: &Path,
    version: &InjectedSecretVersion,
) -> Result<(), InjectedSecretProvisionError> {
    let mut options = OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    options.mode(0o400);
    let mut file = options
        .open(path)
        .map_err(|_| InjectedSecretProvisionError)?;
    file.write_all(version.as_str().as_bytes())
        .and_then(|_| file.sync_all())
        .map_err(|_| InjectedSecretProvisionError)
}

fn set_private_directory_mode(path: &Path) -> Result<(), InjectedSecretProvisionError> {
    #[cfg(unix)]
    fs::set_permissions(path, fs::Permissions::from_mode(0o700))
        .map_err(|_| InjectedSecretProvisionError)?;
    Ok(())
}

/// A path-free failure from Local foundation Secret projection setup.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("Injected Secret projection could not be initialized")]
pub struct InjectedSecretProvisionError;

/// Safe failure while an existing Local foundation capability is projected to
/// one additional workload root during an additive deployment migration.
#[derive(Debug, Error)]
pub enum LocalInjectedSecretReplicationError {
    #[error("source Injected Secret could not be captured: {0}")]
    Source(InjectedSecretError),
    #[error("target Injected Secret could not be inspected: {0}")]
    Target(InjectedSecretError),
    #[error("target Injected Secret does not match its source")]
    TargetMismatch,
    #[error(transparent)]
    Provision(InjectedSecretProvisionError),
}

/// Replicates one immutable Local foundation projection into another workload
/// root without returning its material to the caller. An existing valid target
/// is retained, making the additive migration safe to rerun.
pub fn replicate_injected_projection_for_local_foundation(
    source_root: &Path,
    target_root: &Path,
    reference: &InjectedSecretReference,
) -> Result<(), LocalInjectedSecretReplicationError> {
    let source = InjectedSecretSnapshot::capture_from_root(source_root, reference)
        .map_err(LocalInjectedSecretReplicationError::Source)?;
    fs::create_dir_all(target_root).map_err(|_| {
        LocalInjectedSecretReplicationError::Provision(InjectedSecretProvisionError)
    })?;
    set_private_directory_mode(target_root)
        .map_err(LocalInjectedSecretReplicationError::Provision)?;
    match InjectedSecretSnapshot::capture_from_root(target_root, reference) {
        Ok(target) => {
            let material_matches = source.material().expose(|source_material| {
                target
                    .material()
                    .expose(|target_material| source_material == target_material)
            });
            if source.version() == target.version() && material_matches {
                return Ok(());
            }
            return Err(LocalInjectedSecretReplicationError::TargetMismatch);
        }
        Err(error) if error.kind() == InjectedSecretErrorKind::Missing => {}
        Err(error) => return Err(LocalInjectedSecretReplicationError::Target(error)),
    }

    let directory = reference
        .segments()
        .fold(target_root.to_path_buf(), |path, segment| {
            path.join(segment)
        });
    let parent = directory
        .parent()
        .ok_or(InjectedSecretProvisionError)
        .map_err(LocalInjectedSecretReplicationError::Provision)?;
    fs::create_dir_all(parent).map_err(|_| {
        LocalInjectedSecretReplicationError::Provision(InjectedSecretProvisionError)
    })?;
    set_private_directory_mode(parent).map_err(LocalInjectedSecretReplicationError::Provision)?;
    if let Ok(metadata) = fs::symlink_metadata(&directory) {
        if metadata.file_type().is_symlink() || !metadata.is_dir() {
            return Err(LocalInjectedSecretReplicationError::Provision(
                InjectedSecretProvisionError,
            ));
        }
        fs::remove_dir_all(&directory).map_err(|_| {
            LocalInjectedSecretReplicationError::Provision(InjectedSecretProvisionError)
        })?;
    }

    let staged = parent.join(format!(".replication-{}", uuid::Uuid::new_v4()));
    let install = (|| {
        fs::create_dir(&staged).map_err(|_| InjectedSecretProvisionError)?;
        set_private_directory_mode(&staged)?;
        write_new_private_projection_file(&staged.join("value"), source.material())?;
        write_new_version_projection_file(&staged.join("version"), source.version())?;
        File::open(&staged)
            .and_then(|staged_directory| staged_directory.sync_all())
            .map_err(|_| InjectedSecretProvisionError)?;
        fs::rename(&staged, &directory).map_err(|_| InjectedSecretProvisionError)?;
        File::open(parent)
            .and_then(|parent_directory| parent_directory.sync_all())
            .map_err(|_| InjectedSecretProvisionError)
    })();
    if install.is_err() {
        let _ = fs::remove_dir_all(&staged);
    }
    install.map_err(LocalInjectedSecretReplicationError::Provision)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
pub enum SecretMaterialError {
    #[error("Secret material exceeds the 64 KiB limit")]
    TooLarge,
}

/// One Injected reference and the exact projected version required by startup.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InjectedSecretRequirement {
    uri: InjectedSecretReference,
    expected_version: InjectedSecretVersion,
}

impl InjectedSecretRequirement {
    pub fn new(uri: InjectedSecretReference, expected_version: InjectedSecretVersion) -> Self {
        Self {
            uri,
            expected_version,
        }
    }

    pub fn reference(&self) -> &InjectedSecretReference {
        &self.uri
    }

    pub fn expected_version(&self) -> &InjectedSecretVersion {
        &self.expected_version
    }
}

/// One protected Injected value retained by a process-lifetime snapshot.
pub struct ResolvedInjectedSecret {
    reference: InjectedSecretReference,
    version: InjectedSecretVersion,
    material: SecretMaterial,
}

impl ResolvedInjectedSecret {
    pub fn reference(&self) -> &InjectedSecretReference {
        &self.reference
    }

    pub fn version(&self) -> &InjectedSecretVersion {
        &self.version
    }

    pub fn material(&self) -> &SecretMaterial {
        &self.material
    }
}

impl fmt::Debug for ResolvedInjectedSecret {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ResolvedInjectedSecret")
            .field("reference", &self.reference)
            .field("version", &self.version)
            .field("material", &self.material)
            .finish()
    }
}

/// Immutable set of Injected secrets resolved once during process bootstrap.
pub struct InjectedSecretSnapshot {
    entries: BTreeMap<InjectedSecretReference, ResolvedInjectedSecret>,
}

impl InjectedSecretSnapshot {
    /// Resolves the complete required set beneath the fixed production root.
    pub fn load(
        requirements: impl IntoIterator<Item = InjectedSecretRequirement>,
    ) -> Result<Self, InjectedSecretError> {
        Self::load_from_root(Path::new(INJECTED_SECRET_ROOT), requirements)
    }

    pub fn get(&self, reference: &InjectedSecretReference) -> Option<&ResolvedInjectedSecret> {
        self.entries.get(reference)
    }

    pub fn iter(&self) -> impl Iterator<Item = &ResolvedInjectedSecret> {
        self.entries.values()
    }

    pub fn len(&self) -> usize {
        self.entries.len()
    }

    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Captures one projection without assigning an expected version. This is
    /// used at process bootstrap when a later selected path owns the version
    /// check but must never cause a filesystem reread.
    pub fn capture(
        reference: &InjectedSecretReference,
    ) -> Result<ResolvedInjectedSecret, InjectedSecretError> {
        Self::capture_from_root(Path::new(INJECTED_SECRET_ROOT), reference)
    }

    fn load_from_root(
        root: &Path,
        requirements: impl IntoIterator<Item = InjectedSecretRequirement>,
    ) -> Result<Self, InjectedSecretError> {
        let root = InjectedRoot::open(root)?;

        let mut seen = BTreeSet::new();
        let mut entries = BTreeMap::new();
        for requirement in requirements {
            if !seen.insert(requirement.reference().clone()) {
                return Err(InjectedSecretError::for_reference(
                    InjectedSecretErrorKind::DuplicateReference,
                    requirement.reference(),
                ));
            }
            let resolved = resolve_injected(&root, &requirement)?;
            entries.insert(requirement.uri, resolved);
        }
        Ok(Self { entries })
    }

    #[cfg(any(test, feature = "test-fixtures"))]
    #[doc(hidden)]
    pub fn load_from_root_for_test(
        root: &Path,
        requirements: impl IntoIterator<Item = InjectedSecretRequirement>,
    ) -> Result<Self, InjectedSecretError> {
        Self::load_from_root(root, requirements)
    }

    #[cfg(any(test, feature = "test-fixtures"))]
    #[doc(hidden)]
    pub fn capture_from_root_for_test(
        root: &Path,
        reference: &InjectedSecretReference,
    ) -> Result<ResolvedInjectedSecret, InjectedSecretError> {
        Self::capture_from_root(root, reference)
    }

    fn capture_from_root(
        root: &Path,
        reference: &InjectedSecretReference,
    ) -> Result<ResolvedInjectedSecret, InjectedSecretError> {
        let root = InjectedRoot::open(root)?;
        capture_injected(&root, reference)
    }
}

impl fmt::Debug for InjectedSecretSnapshot {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("InjectedSecretSnapshot")
            .field("entries", &self.entries)
            .finish()
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InjectedSecretErrorKind {
    RootUnavailable,
    Missing,
    EscapesRoot,
    NotRegularFile,
    UnsafePermissions,
    Unreadable,
    TooLarge,
    InvalidVersion,
    VersionMismatch,
    ChangedDuringSnapshot,
    DuplicateReference,
    UnsupportedPlatform,
}

impl fmt::Display for InjectedSecretErrorKind {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let category = match self {
            Self::RootUnavailable => "root unavailable",
            Self::Missing => "projection missing",
            Self::EscapesRoot => "projection escapes fixed root",
            Self::NotRegularFile => "projection is not a regular file",
            Self::UnsafePermissions => "projection has unsafe permissions",
            Self::Unreadable => "projection is not readable by the effective identity",
            Self::TooLarge => "Secret material exceeds the 64 KiB limit",
            Self::InvalidVersion => "projected version label is invalid",
            Self::VersionMismatch => "projected version does not match the expected version",
            Self::ChangedDuringSnapshot => "projection changed while the snapshot was loading",
            Self::DuplicateReference => "reference occurs more than once in the snapshot request",
            Self::UnsupportedPlatform => {
                "filesystem identity checks are unsupported on this platform"
            }
        };
        formatter.write_str(category)
    }
}

/// Safe Injected-secret failure containing no material or filesystem path.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InjectedSecretError {
    kind: InjectedSecretErrorKind,
    reference: Option<InjectedSecretReference>,
}

impl InjectedSecretError {
    pub fn kind(&self) -> InjectedSecretErrorKind {
        self.kind
    }

    pub fn reference(&self) -> Option<&InjectedSecretReference> {
        self.reference.as_ref()
    }

    fn for_reference(kind: InjectedSecretErrorKind, reference: &InjectedSecretReference) -> Self {
        Self {
            kind,
            reference: Some(reference.clone()),
        }
    }

    fn without_reference(kind: InjectedSecretErrorKind) -> Self {
        Self {
            kind,
            reference: None,
        }
    }
}

impl fmt::Display for InjectedSecretError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.reference {
            Some(reference) => write!(formatter, "Injected secret {reference}: {}", self.kind),
            None => write!(formatter, "Injected-secret snapshot: {}", self.kind),
        }
    }
}

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

// The fields are only read by the Linux `openat2` projection path; other
// platforms never construct a root because `open` reports `UnsupportedPlatform`.
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
struct InjectedRoot {
    directory: File,
    canonical_path: PathBuf,
}

impl InjectedRoot {
    #[cfg(target_os = "linux")]
    fn open(path: &Path) -> Result<Self, InjectedSecretError> {
        let directory = File::open(path).map_err(|_| {
            InjectedSecretError::without_reference(InjectedSecretErrorKind::RootUnavailable)
        })?;
        let metadata = directory.metadata().map_err(|_| {
            InjectedSecretError::without_reference(InjectedSecretErrorKind::RootUnavailable)
        })?;
        if !metadata.is_dir() {
            return Err(InjectedSecretError::without_reference(
                InjectedSecretErrorKind::RootUnavailable,
            ));
        }
        validate_directory_permissions(&metadata)
            .map_err(InjectedSecretError::without_reference)?;
        let canonical_path =
            descriptor_path(&directory).map_err(InjectedSecretError::without_reference)?;
        Ok(Self {
            directory,
            canonical_path,
        })
    }

    #[cfg(not(target_os = "linux"))]
    fn open(_path: &Path) -> Result<Self, InjectedSecretError> {
        Err(InjectedSecretError::without_reference(
            InjectedSecretErrorKind::UnsupportedPlatform,
        ))
    }
}

fn resolve_injected(
    root: &InjectedRoot,
    requirement: &InjectedSecretRequirement,
) -> Result<ResolvedInjectedSecret, InjectedSecretError> {
    let resolved = capture_injected(root, requirement.reference())?;
    if resolved.version() != requirement.expected_version() {
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::VersionMismatch,
            requirement.reference(),
        ));
    }
    Ok(resolved)
}

fn capture_injected(
    root: &InjectedRoot,
    reference: &InjectedSecretReference,
) -> Result<ResolvedInjectedSecret, InjectedSecretError> {
    let projection_directory = reference
        .segments()
        .fold(PathBuf::new(), |path, segment| path.join(segment));
    validate_projection_directory_chain(root, reference)?;

    let initial_version = read_projection_file(
        root,
        &projection_directory.join("version"),
        ProjectionFile::Version,
        reference,
    )?;
    let version = parse_projected_version(&initial_version.bytes, reference)?;

    let mut material_read = read_projection_file(
        root,
        &projection_directory.join("value"),
        ProjectionFile::Value,
        reference,
    )?;
    if !initial_version.same_generation(&material_read) {
        material_read.bytes.zeroize();
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        ));
    }
    let material = SecretMaterial::try_from(material_read.bytes).map_err(|_| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::TooLarge, reference)
    })?;
    let confirmed_version = read_projection_file(
        root,
        &projection_directory.join("version"),
        ProjectionFile::Version,
        reference,
    )?;
    if !initial_version.same_generation(&confirmed_version)
        || !initial_version.same_file_and_content(&confirmed_version)
    {
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        ));
    }
    Ok(ResolvedInjectedSecret {
        reference: reference.clone(),
        version,
        material,
    })
}

pub(crate) fn load_root_identity_material() -> Result<SecretMaterial, InjectedSecretError> {
    load_root_identity_material_from_root(Path::new(INJECTED_SECRET_ROOT))
}

fn load_root_identity_material_from_root(
    root_path: &Path,
) -> Result<SecretMaterial, InjectedSecretError> {
    load_named_identity_material_from_root(root_path, "root-identity")
}

pub(crate) fn load_next_root_identity_material() -> Result<SecretMaterial, InjectedSecretError> {
    load_named_identity_material_from_root(Path::new(INJECTED_SECRET_ROOT), "root-identity-next")
}

#[cfg(any(test, feature = "test-fixtures"))]
pub(crate) fn load_next_root_identity_material_from_root(
    root_path: &Path,
) -> Result<SecretMaterial, InjectedSecretError> {
    load_named_identity_material_from_root(root_path, "root-identity-next")
}

fn load_named_identity_material_from_root(
    root_path: &Path,
    name: &str,
) -> Result<SecretMaterial, InjectedSecretError> {
    let reference = InjectedSecretReference::from_str(&format!("injected://ahri-tre/{name}"))
        .map_err(|_| {
            InjectedSecretError::without_reference(InjectedSecretErrorKind::UnsupportedPlatform)
        })?;
    let root = InjectedRoot::open(root_path)?;
    validate_projection_directory_chain(&root, &reference)?;
    let mut material_read = read_projection_file(
        &root,
        &Path::new("ahri-tre").join(name).join("value"),
        ProjectionFile::Value,
        &reference,
    )?;
    SecretMaterial::try_from(std::mem::take(&mut material_read.bytes)).map_err(|_| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::TooLarge, &reference)
    })
}

fn parse_projected_version(
    bytes: &[u8],
    reference: &InjectedSecretReference,
) -> Result<InjectedSecretVersion, InjectedSecretError> {
    let version_text = std::str::from_utf8(bytes).map_err(|_| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::InvalidVersion, reference)
    })?;
    InjectedSecretVersion::from_str(version_text).map_err(|_| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::InvalidVersion, reference)
    })
}

#[cfg(target_os = "linux")]
fn validate_projection_directory_chain(
    root: &InjectedRoot,
    reference: &InjectedSecretReference,
) -> Result<(), InjectedSecretError> {
    let projected = reference
        .segments()
        .fold(PathBuf::new(), |path, segment| path.join(segment));
    open_validated_directory_chain(root, &projected, reference)?;
    Ok(())
}

#[cfg(not(target_os = "linux"))]
fn validate_projection_directory_chain(
    _root: &InjectedRoot,
    reference: &InjectedSecretReference,
) -> Result<(), InjectedSecretError> {
    Err(InjectedSecretError::for_reference(
        InjectedSecretErrorKind::UnsupportedPlatform,
        reference,
    ))
}

#[derive(Clone, Copy)]
enum ProjectionFile {
    Value,
    Version,
}

#[cfg(target_os = "linux")]
impl ProjectionFile {
    fn limit(self) -> usize {
        match self {
            Self::Value => MAX_SECRET_MATERIAL_BYTES,
            Self::Version => 64,
        }
    }

    fn oversized_error(self) -> InjectedSecretErrorKind {
        match self {
            Self::Value => InjectedSecretErrorKind::TooLarge,
            Self::Version => InjectedSecretErrorKind::InvalidVersion,
        }
    }
}

struct ProjectionRead {
    bytes: Vec<u8>,
    identity: FileIdentity,
    generation: ProjectionGeneration,
}

impl ProjectionRead {
    fn same_file_and_content(&self, other: &Self) -> bool {
        self.identity == other.identity && self.bytes == other.bytes
    }

    fn same_generation(&self, other: &Self) -> bool {
        self.generation == other.generation
    }
}

#[derive(PartialEq, Eq)]
struct ProjectionGeneration {
    identity: FileIdentity,
}

#[derive(PartialEq, Eq)]
struct FileIdentity {
    device: u64,
    inode: u64,
    length: u64,
    modified_seconds: i64,
    modified_nanoseconds: i64,
    changed_seconds: i64,
    changed_nanoseconds: i64,
}

#[cfg(target_os = "linux")]
fn file_identity(metadata: &fs::Metadata) -> FileIdentity {
    FileIdentity {
        device: metadata.dev(),
        inode: metadata.ino(),
        length: metadata.len(),
        modified_seconds: metadata.mtime(),
        modified_nanoseconds: metadata.mtime_nsec(),
        changed_seconds: metadata.ctime(),
        changed_nanoseconds: metadata.ctime_nsec(),
    }
}

#[cfg(target_os = "linux")]
fn read_projection_file(
    root: &InjectedRoot,
    projected_path: &Path,
    file_kind: ProjectionFile,
    reference: &InjectedSecretReference,
) -> Result<ProjectionRead, InjectedSecretError> {
    let file = open_beneath(
        root,
        projected_path,
        OFlags::RDONLY | OFlags::CLOEXEC,
        reference,
    )?;
    let metadata = file.metadata().map_err(|_| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::Unreadable, reference)
    })?;
    if !metadata.is_file() {
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::NotRegularFile,
            reference,
        ));
    }
    validate_file_permissions(&metadata, file_kind)
        .map_err(|kind| InjectedSecretError::for_reference(kind, reference))?;
    let identity_before_read = file_identity(&metadata);
    let generation_before_read =
        anchored_generation(root, &file, &identity_before_read, reference)?;

    let limit = file_kind.limit();
    if metadata.len() > limit as u64 {
        return Err(InjectedSecretError::for_reference(
            file_kind.oversized_error(),
            reference,
        ));
    }

    let mut bytes = Vec::with_capacity(metadata.len() as usize);
    if (&file)
        .take((limit + 1) as u64)
        .read_to_end(&mut bytes)
        .is_err()
    {
        bytes.zeroize();
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::Unreadable,
            reference,
        ));
    }
    if bytes.len() > limit {
        bytes.zeroize();
        return Err(InjectedSecretError::for_reference(
            file_kind.oversized_error(),
            reference,
        ));
    }
    let identity_after_read = file
        .metadata()
        .map(|metadata| file_identity(&metadata))
        .map_err(|_| {
            InjectedSecretError::for_reference(
                InjectedSecretErrorKind::ChangedDuringSnapshot,
                reference,
            )
        })?;
    if identity_before_read != identity_after_read {
        bytes.zeroize();
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        ));
    }
    let generation_after_read = anchored_generation(root, &file, &identity_after_read, reference)?;
    if generation_before_read != generation_after_read {
        bytes.zeroize();
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        ));
    }
    Ok(ProjectionRead {
        bytes,
        identity: identity_after_read,
        generation: generation_after_read,
    })
}

#[cfg(not(target_os = "linux"))]
fn read_projection_file(
    _root: &InjectedRoot,
    _projected_path: &Path,
    _file_kind: ProjectionFile,
    reference: &InjectedSecretReference,
) -> Result<ProjectionRead, InjectedSecretError> {
    Err(InjectedSecretError::for_reference(
        InjectedSecretErrorKind::UnsupportedPlatform,
        reference,
    ))
}

#[cfg(target_os = "linux")]
fn open_beneath(
    root: &InjectedRoot,
    relative_path: &Path,
    flags: OFlags,
    reference: &InjectedSecretReference,
) -> Result<File, InjectedSecretError> {
    let descriptor = openat2(
        &root.directory,
        relative_path,
        flags,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| {
        let kind = if error == rustix::io::Errno::XDEV || error == rustix::io::Errno::LOOP {
            InjectedSecretErrorKind::EscapesRoot
        } else if error == rustix::io::Errno::NOSYS {
            InjectedSecretErrorKind::UnsupportedPlatform
        } else if error == rustix::io::Errno::ACCESS {
            InjectedSecretErrorKind::Unreadable
        } else if error == rustix::io::Errno::AGAIN {
            InjectedSecretErrorKind::ChangedDuringSnapshot
        } else {
            InjectedSecretErrorKind::Missing
        };
        InjectedSecretError::for_reference(kind, reference)
    })?;
    Ok(File::from(descriptor))
}

#[cfg(target_os = "linux")]
fn open_validated_directory_chain(
    root: &InjectedRoot,
    relative_path: &Path,
    reference: &InjectedSecretReference,
) -> Result<File, InjectedSecretError> {
    let mut current = PathBuf::new();
    let mut final_directory = None;
    for component in relative_path.components() {
        let std::path::Component::Normal(component) = component else {
            return Err(InjectedSecretError::for_reference(
                InjectedSecretErrorKind::EscapesRoot,
                reference,
            ));
        };
        current.push(component);
        let directory = open_beneath(
            root,
            &current,
            OFlags::PATH | OFlags::DIRECTORY | OFlags::CLOEXEC,
            reference,
        )?;
        let metadata = directory.metadata().map_err(|_| {
            InjectedSecretError::for_reference(InjectedSecretErrorKind::Missing, reference)
        })?;
        validate_directory_permissions(&metadata)
            .map_err(|kind| InjectedSecretError::for_reference(kind, reference))?;
        final_directory = Some(directory);
    }
    final_directory.ok_or_else(|| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::EscapesRoot, reference)
    })
}

#[cfg(target_os = "linux")]
fn descriptor_path(file: &File) -> Result<PathBuf, InjectedSecretErrorKind> {
    fs::read_link(format!("/proc/self/fd/{}", file.as_raw_fd()))
        .map_err(|_| InjectedSecretErrorKind::UnsupportedPlatform)
}

#[cfg(target_os = "linux")]
fn anchored_generation(
    root: &InjectedRoot,
    file: &File,
    expected_file_identity: &FileIdentity,
    reference: &InjectedSecretReference,
) -> Result<ProjectionGeneration, InjectedSecretError> {
    let opened_path = descriptor_path(file)
        .map_err(|kind| InjectedSecretError::for_reference(kind, reference))?;
    let relative_path = opened_path
        .strip_prefix(&root.canonical_path)
        .map_err(|_| {
            InjectedSecretError::for_reference(InjectedSecretErrorKind::EscapesRoot, reference)
        })?;
    let parent = relative_path.parent().ok_or_else(|| {
        InjectedSecretError::for_reference(InjectedSecretErrorKind::EscapesRoot, reference)
    })?;
    let file_name = relative_path.file_name().ok_or_else(|| {
        InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        )
    })?;
    let generation_directory = open_validated_directory_chain(root, parent, reference)?;
    let current_file = openat2(
        &generation_directory,
        Path::new(file_name),
        OFlags::PATH | OFlags::CLOEXEC,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_MAGICLINKS | ResolveFlags::NO_SYMLINKS,
    )
    .map(File::from)
    .map_err(|_| {
        InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        )
    })?;
    let current_identity = current_file
        .metadata()
        .map(|metadata| file_identity(&metadata))
        .map_err(|_| {
            InjectedSecretError::for_reference(
                InjectedSecretErrorKind::ChangedDuringSnapshot,
                reference,
            )
        })?;
    if &current_identity != expected_file_identity {
        return Err(InjectedSecretError::for_reference(
            InjectedSecretErrorKind::ChangedDuringSnapshot,
            reference,
        ));
    }
    let identity = generation_directory
        .metadata()
        .map(|metadata| file_identity(&metadata))
        .map_err(|_| {
            InjectedSecretError::for_reference(
                InjectedSecretErrorKind::ChangedDuringSnapshot,
                reference,
            )
        })?;
    Ok(ProjectionGeneration { identity })
}

#[cfg(target_os = "linux")]
fn validate_directory_permissions(metadata: &fs::Metadata) -> Result<(), InjectedSecretErrorKind> {
    if metadata.mode() & 0o022 != 0 {
        return Err(InjectedSecretErrorKind::UnsafePermissions);
    }
    Ok(())
}

#[cfg(target_os = "linux")]
fn validate_file_permissions(
    metadata: &fs::Metadata,
    file_kind: ProjectionFile,
) -> Result<(), InjectedSecretErrorKind> {
    let mode = metadata.mode();
    match file_kind {
        ProjectionFile::Value => {
            if mode & 0o333 != 0 || mode & 0o007 != 0 {
                return Err(InjectedSecretErrorKind::UnsafePermissions);
            }
            if !effective_identity_can_read(metadata)? {
                return Err(InjectedSecretErrorKind::Unreadable);
            }
        }
        ProjectionFile::Version => {
            if mode & 0o133 != 0 {
                return Err(InjectedSecretErrorKind::UnsafePermissions);
            }
        }
    }
    Ok(())
}

#[cfg(target_os = "linux")]
fn effective_identity_can_read(metadata: &fs::Metadata) -> Result<bool, InjectedSecretErrorKind> {
    // SAFETY: These libc identity queries have no preconditions and do not
    // dereference caller-provided memory.
    let effective_uid = unsafe { libc::geteuid() };
    // SAFETY: `getegid` has no preconditions and returns the process identity.
    let effective_gid = unsafe { libc::getegid() };
    // SAFETY: A zero-sized `getgroups` call accepts a null pointer and returns
    // the buffer size required for the subsequent call.
    let count = unsafe { libc::getgroups(0, std::ptr::null_mut()) };
    if count < 0 {
        return Err(InjectedSecretErrorKind::Unreadable);
    }
    let mut groups = vec![0; count as usize];
    if count > 0 {
        // SAFETY: `groups` has exactly `count` writable `gid_t` elements.
        let result = unsafe { libc::getgroups(count, groups.as_mut_ptr()) };
        if result < 0 {
            return Err(InjectedSecretErrorKind::Unreadable);
        }
        groups.truncate(result as usize);
    }
    groups.push(effective_gid);
    Ok(permission_class_can_read(
        metadata.mode(),
        metadata.uid(),
        metadata.gid(),
        effective_uid,
        &groups,
    ))
}

#[cfg(any(target_os = "linux", test))]
fn permission_class_can_read(
    mode: u32,
    file_uid: libc::uid_t,
    file_gid: libc::gid_t,
    effective_uid: libc::uid_t,
    effective_groups: &[libc::gid_t],
) -> bool {
    if file_uid == effective_uid {
        mode & 0o400 != 0
    } else {
        mode & 0o040 != 0 && effective_groups.contains(&file_gid)
    }
}

#[cfg(test)]
mod tests {
    use super::{
        InjectedSecretErrorKind, InjectedSecretReference, InjectedSecretRequirement,
        InjectedSecretSnapshot, InjectedSecretVersion, LocalInjectedSecretReplicationError,
        MAX_SECRET_MATERIAL_BYTES, ManagedSecretReference, SecretMaterial, SecretReference,
        initialize_injected_projection_for_local_foundation, permission_class_can_read,
        remove_injected_projection_for_local_acceptance,
        replace_injected_projection_for_local_acceptance, replace_local_provider_credential,
        replicate_injected_projection_for_local_foundation, write_new_local_provider_credential,
    };
    use std::fs;
    use std::os::unix::fs::{MetadataExt, PermissionsExt, symlink};
    use std::path::{Path, PathBuf};
    use std::str::FromStr;
    use std::sync::atomic::{AtomicU64, Ordering};
    use uuid::Uuid;

    #[test]
    fn canonical_references_accept_every_defined_boundary() {
        let one_segment = SecretReference::from_str("managed://a").unwrap();
        assert_eq!(one_segment.as_str(), "managed://a");

        let eight_segments = SecretReference::from_str(
            "injected://a/segment-2/3/4/5/6/7/abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyza",
        )
        .unwrap();
        assert_eq!(eight_segments.segments().count(), 8);

        let managed = ManagedSecretReference::from_str("managed://0").unwrap();
        assert_eq!(managed.as_str(), "managed://0");
        let injected = InjectedSecretReference::from_str("injected://a-1").unwrap();
        assert_eq!(injected.as_str(), "injected://a-1");

        let maximum_uri = format!(
            "managed://{}/{}/{}/{}/{}/{}/{}/{}",
            "a".repeat(63),
            "b".repeat(63),
            "c".repeat(63),
            "d".repeat(63),
            "e".repeat(63),
            "f".repeat(63),
            "g".repeat(63),
            "h".repeat(54),
        );
        assert_eq!(maximum_uri.len(), 512);
        assert!(SecretReference::from_str(&maximum_uri).is_ok());
    }

    #[test]
    fn local_foundation_writes_a_new_safe_injected_projection() {
        let fixture = InjectedFixture::new();
        let reference =
            InjectedSecretReference::from_str("injected://runtime/private-key").unwrap();
        let version = InjectedSecretVersion::from_str("local-v1").unwrap();
        let material = SecretMaterial::try_from(b"local-private-material".to_vec()).unwrap();

        initialize_injected_projection_for_local_foundation(
            fixture.root(),
            &reference,
            &version,
            &material,
        )
        .unwrap();

        let snapshot = InjectedSecretSnapshot::load_from_root_for_test(
            fixture.root(),
            [InjectedSecretRequirement::new(reference.clone(), version)],
        )
        .unwrap();
        snapshot
            .get(&reference)
            .unwrap()
            .material()
            .expose(|value| assert_eq!(value, b"local-private-material"));
        assert!(
            initialize_injected_projection_for_local_foundation(
                fixture.root(),
                &reference,
                &InjectedSecretVersion::from_str("local-v1").unwrap(),
                &material,
            )
            .is_err()
        );
    }

    #[test]
    fn local_foundation_replicates_an_existing_projection_without_exposing_it() {
        let source = InjectedFixture::new();
        let target = InjectedFixture::new();
        let reference =
            InjectedSecretReference::from_str("injected://web/workflow-entry-password").unwrap();
        let version = InjectedSecretVersion::from_str("local-v1").unwrap();
        let material = SecretMaterial::try_from(b"workflow-entry-material".to_vec()).unwrap();
        initialize_injected_projection_for_local_foundation(
            source.root(),
            &reference,
            &version,
            &material,
        )
        .unwrap();

        replicate_injected_projection_for_local_foundation(
            source.root(),
            target.root(),
            &reference,
        )
        .unwrap();
        replicate_injected_projection_for_local_foundation(
            source.root(),
            target.root(),
            &reference,
        )
        .unwrap();

        let snapshot = InjectedSecretSnapshot::load_from_root_for_test(
            target.root(),
            [InjectedSecretRequirement::new(reference.clone(), version)],
        )
        .unwrap();
        snapshot
            .get(&reference)
            .unwrap()
            .material()
            .expose(|value| assert_eq!(value, b"workflow-entry-material"));
    }

    #[test]
    fn local_foundation_replication_recovers_an_incomplete_target_atomically() {
        let source = InjectedFixture::new();
        let target = InjectedFixture::new();
        let reference =
            InjectedSecretReference::from_str("injected://web/workflow-entry-password").unwrap();
        let version = InjectedSecretVersion::from_str("local-v1").unwrap();
        let material = SecretMaterial::try_from(b"workflow-entry-material".to_vec()).unwrap();
        initialize_injected_projection_for_local_foundation(
            source.root(),
            &reference,
            &version,
            &material,
        )
        .unwrap();
        let incomplete = target.root().join("web/workflow-entry-password");
        fs::create_dir_all(&incomplete).unwrap();
        fs::set_permissions(&incomplete, fs::Permissions::from_mode(0o700)).unwrap();
        fs::write(incomplete.join("value"), b"partial-material").unwrap();
        fs::set_permissions(incomplete.join("value"), fs::Permissions::from_mode(0o400)).unwrap();

        replicate_injected_projection_for_local_foundation(
            source.root(),
            target.root(),
            &reference,
        )
        .unwrap();

        let snapshot = InjectedSecretSnapshot::load_from_root_for_test(
            target.root(),
            [InjectedSecretRequirement::new(reference.clone(), version)],
        )
        .unwrap();
        snapshot
            .get(&reference)
            .unwrap()
            .material()
            .expose(|value| assert_eq!(value, b"workflow-entry-material"));
    }

    #[test]
    fn local_foundation_replication_rejects_a_mismatched_existing_target() {
        let source = InjectedFixture::new();
        let target = InjectedFixture::new();
        let reference =
            InjectedSecretReference::from_str("injected://web/workflow-entry-password").unwrap();
        let version = InjectedSecretVersion::from_str("local-v1").unwrap();
        let source_material =
            SecretMaterial::try_from(b"workflow-entry-material".to_vec()).unwrap();
        let target_material = SecretMaterial::try_from(b"different-material".to_vec()).unwrap();
        initialize_injected_projection_for_local_foundation(
            source.root(),
            &reference,
            &version,
            &source_material,
        )
        .unwrap();
        initialize_injected_projection_for_local_foundation(
            target.root(),
            &reference,
            &version,
            &target_material,
        )
        .unwrap();

        assert!(matches!(
            replicate_injected_projection_for_local_foundation(
                source.root(),
                target.root(),
                &reference,
            ),
            Err(LocalInjectedSecretReplicationError::TargetMismatch)
        ));
        let snapshot = InjectedSecretSnapshot::load_from_root_for_test(
            target.root(),
            [InjectedSecretRequirement::new(reference.clone(), version)],
        )
        .unwrap();
        snapshot
            .get(&reference)
            .unwrap()
            .material()
            .expose(|value| assert_eq!(value, b"different-material"));
    }

    #[test]
    fn local_provider_credential_is_private_from_creation_and_never_replaced() {
        let fixture = InjectedFixture::new();
        fs::set_permissions(fixture.root(), fs::Permissions::from_mode(0o700)).unwrap();
        let path = fixture.root().join("provider-credential");
        let first = SecretMaterial::try_from(b"first-provider-value".to_vec()).unwrap();
        let second = SecretMaterial::try_from(b"second-provider-value".to_vec()).unwrap();

        write_new_local_provider_credential(&path, &first).unwrap();

        assert_eq!(
            fs::metadata(&path).unwrap().permissions().mode() & 0o777,
            0o400
        );
        assert_eq!(fs::read(&path).unwrap(), b"first-provider-value");
        assert!(write_new_local_provider_credential(&path, &second).is_err());
        assert_eq!(fs::read(&path).unwrap(), b"first-provider-value");
    }

    #[test]
    fn diagnostic_provider_replacement_requires_and_preserves_a_private_owned_file() {
        let fixture = InjectedFixture::new();
        fs::set_permissions(fixture.root(), fs::Permissions::from_mode(0o700)).unwrap();
        let path = fixture.root().join("provider-credential");
        let first = SecretMaterial::try_from(b"first-provider-value".to_vec()).unwrap();
        let second = SecretMaterial::try_from(b"second-provider-value".to_vec()).unwrap();
        write_new_local_provider_credential(&path, &first).unwrap();

        replace_local_provider_credential(&path, &second).unwrap();

        assert_eq!(fs::read(&path).unwrap(), b"second-provider-value");
        let metadata = fs::metadata(&path).unwrap();
        assert_eq!(metadata.permissions().mode() & 0o777, 0o400);
        assert_eq!(metadata.nlink(), 1);
    }

    #[test]
    fn temporary_acceptance_projection_replaces_and_revokes_only_its_capability() {
        let fixture = InjectedFixture::new();
        let temporary =
            InjectedSecretReference::from_str("injected://orcid-sandbox/client-secret").unwrap();
        let sibling = InjectedSecretReference::from_str("injected://runtime/private-key").unwrap();
        let version = InjectedSecretVersion::from_str("sandbox-v1").unwrap();
        let first = SecretMaterial::try_from(b"first-value".to_vec()).unwrap();
        let second = SecretMaterial::try_from(b"second-value".to_vec()).unwrap();
        let sibling_material = SecretMaterial::try_from(b"runtime-value".to_vec()).unwrap();
        initialize_injected_projection_for_local_foundation(
            fixture.root(),
            &sibling,
            &version,
            &sibling_material,
        )
        .unwrap();

        replace_injected_projection_for_local_acceptance(
            fixture.root(),
            &temporary,
            &version,
            &first,
        )
        .unwrap();
        replace_injected_projection_for_local_acceptance(
            fixture.root(),
            &temporary,
            &version,
            &second,
        )
        .unwrap();
        let snapshot = InjectedSecretSnapshot::load_from_root_for_test(
            fixture.root(),
            [InjectedSecretRequirement::new(
                temporary.clone(),
                version.clone(),
            )],
        )
        .unwrap();
        snapshot
            .get(&temporary)
            .unwrap()
            .material()
            .expose(|value| assert_eq!(value, b"second-value"));

        remove_injected_projection_for_local_acceptance(fixture.root(), &temporary).unwrap();
        assert!(!fixture.root().join("orcid-sandbox/client-secret").exists());
        assert!(fixture.root().join("runtime/private-key/value").is_file());
    }

    #[test]
    fn temporary_acceptance_projection_refuses_symlinked_ancestors() {
        let fixture = InjectedFixture::new();
        let outside = std::env::temp_dir().join(format!("injected-outside-{}", Uuid::new_v4()));
        fs::create_dir_all(outside.join("client-secret")).unwrap();
        fs::write(outside.join("client-secret/value"), b"must-survive").unwrap();
        symlink(&outside, fixture.root().join("orcid-sandbox")).unwrap();
        let reference =
            InjectedSecretReference::from_str("injected://orcid-sandbox/client-secret").unwrap();

        assert!(
            remove_injected_projection_for_local_acceptance(fixture.root(), &reference).is_err()
        );
        assert_eq!(
            fs::read(outside.join("client-secret/value")).unwrap(),
            b"must-survive"
        );
        fs::remove_file(fixture.root().join("orcid-sandbox")).unwrap();
        fs::remove_dir_all(outside).unwrap();
    }

    #[test]
    fn canonical_references_reject_non_canonical_and_unbounded_forms() {
        for rejected in [
            "unknown://a",
            "MANAGED://a",
            "managed://",
            "managed:///a",
            "managed://a/",
            "managed://a//b",
            "managed://a/../b",
            "managed://a/./b",
            "managed://a%2fb",
            "managed://A",
            "managed://café",
            "managed://a_b",
            "managed://-a",
            "managed://a-",
            "managed://a--b",
            "managed://a?version=1",
            "managed://a#fragment",
            "managed://user@a",
            "managed://a:443",
            "managed://a\\b",
            "managed://a/b/c/d/e/f/g/h/i",
        ] {
            assert!(
                SecretReference::from_str(rejected).is_err(),
                "accepted {rejected}"
            );
        }

        let long_segment = format!("managed://{}", "a".repeat(64));
        assert!(SecretReference::from_str(&long_segment).is_err());

        let long_uri = format!(
            "managed://{}/{}/{}/{}/{}/{}/{}/{}",
            "a".repeat(63),
            "b".repeat(63),
            "c".repeat(63),
            "d".repeat(63),
            "e".repeat(63),
            "f".repeat(63),
            "g".repeat(63),
            "h".repeat(63),
        );
        assert!(long_uri.len() > 512);
        assert!(SecretReference::from_str(&long_uri).is_err());
    }

    #[test]
    fn typed_references_reject_the_other_secret_tier() {
        assert!(ManagedSecretReference::from_str("injected://a").is_err());
        assert!(InjectedSecretReference::from_str("managed://a").is_err());
    }

    #[test]
    fn reference_and_requirement_serde_shapes_are_closed_and_canonical() {
        let reference = InjectedSecretReference::from_str("injected://oauth/key").unwrap();
        assert_eq!(
            serde_json::to_string(&reference).unwrap(),
            "\"injected://oauth/key\""
        );
        let requirement: InjectedSecretRequirement =
            serde_json::from_str(r#"{"uri":"injected://oauth/key","expected_version":"v1"}"#)
                .unwrap();
        assert_eq!(requirement.reference(), &reference);
        assert!(
            serde_json::from_str::<InjectedSecretRequirement>(
                r#"{"uri":"injected://oauth/key","expected_version":"v1","value":"canary"}"#,
            )
            .is_err()
        );
    }

    #[test]
    fn injected_versions_accept_defined_forms_and_boundaries() {
        for accepted in [
            "a",
            "0",
            "2026-07-01",
            "v2.1.0",
            "01234567-89ab-cdef-0123-456789abcdef",
            &"a".repeat(64),
        ] {
            let version = InjectedSecretVersion::from_str(accepted).unwrap();
            assert_eq!(version.as_str(), accepted);
        }
    }

    #[test]
    fn injected_versions_reject_non_canonical_forms() {
        for rejected in [
            "", "A", "café", ".v1", "v1.", "v1..0", "v1-_0", "v1/0", "v1 0", "v1\n",
        ] {
            assert!(
                InjectedSecretVersion::from_str(rejected).is_err(),
                "accepted {rejected:?}"
            );
        }
        assert!(InjectedSecretVersion::from_str(&"a".repeat(65)).is_err());
    }

    #[test]
    fn secret_material_is_bounded_and_redacted() {
        let canary = b"canary-client-secret-value".to_vec();
        let material = SecretMaterial::try_from(canary.clone()).unwrap();
        assert!(material.expose(|value| value == canary));
        let debug = format!("{material:?}");
        assert!(debug.contains(ahri_tre_security::REDACTED_VALUE));
        assert!(!debug.contains("canary-client-secret-value"));

        assert!(SecretMaterial::try_from(vec![0; MAX_SECRET_MATERIAL_BYTES]).is_ok());
        assert!(SecretMaterial::try_from(vec![0; MAX_SECRET_MATERIAL_BYTES + 1]).is_err());
    }

    #[test]
    fn value_readability_uses_the_effective_posix_permission_class() {
        assert!(permission_class_can_read(0o440, 0, 2000, 1000, &[2000]));
        assert!(!permission_class_can_read(0o040, 1000, 2000, 1000, &[2000]));
        assert!(!permission_class_can_read(0o400, 0, 2000, 1000, &[2000]));
    }

    #[test]
    fn injected_snapshot_resolves_material_and_exact_version() {
        let fixture = InjectedFixture::new();
        fixture.project(
            "injected://oauth/orcid/client-secret",
            b"canary-client-secret-value",
            "2026-07-01",
        );
        let requirement = requirement("injected://oauth/orcid/client-secret", "2026-07-01");

        let snapshot =
            InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [requirement.clone()])
                .unwrap();
        let resolved = snapshot.get(requirement.reference()).unwrap();

        assert_eq!(resolved.reference(), requirement.reference());
        assert_eq!(resolved.version().as_str(), "2026-07-01");
        assert!(
            resolved
                .material()
                .expose(|value| { value == b"canary-client-secret-value" })
        );
        assert!(!format!("{resolved:?}").contains("canary-client-secret-value"));
    }

    #[test]
    fn injected_snapshot_follows_only_contained_projection_links() {
        let fixture = InjectedFixture::new();
        let projection =
            fixture.project_linked("injected://tls/runtime-key", b"contained-canary", "v1");
        let requirement = requirement("injected://tls/runtime-key", "v1");
        let snapshot =
            InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [requirement.clone()])
                .unwrap();
        assert!(
            snapshot
                .get(requirement.reference())
                .unwrap()
                .material()
                .expose(|value| value == b"contained-canary")
        );

        let outside_value = fixture.base().join("outside-value");
        fs::write(&outside_value, b"outside-canary").unwrap();
        fs::set_permissions(&outside_value, fs::Permissions::from_mode(0o400)).unwrap();
        fs::remove_file(projection.join("value")).unwrap();
        symlink(&outside_value, projection.join("value")).unwrap();

        let error = InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [requirement])
            .unwrap_err();
        assert_eq!(error.kind(), InjectedSecretErrorKind::EscapesRoot);
        assert!(!format!("{error:?}").contains(outside_value.to_string_lossy().as_ref()));
    }

    #[test]
    fn injected_snapshot_does_not_reopen_replaced_projection_files() {
        let fixture = InjectedFixture::new();
        let projection = fixture.project(
            "injected://oauth/orcid/client-secret",
            b"generation-one",
            "v1",
        );
        let requirement = requirement("injected://oauth/orcid/client-secret", "v1");
        let snapshot =
            InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [requirement.clone()])
                .unwrap();

        write_protected(&projection.join("value"), b"generation-two", 0o400);
        write_protected(&projection.join("version"), b"v2", 0o444);

        let resolved = snapshot.get(requirement.reference()).unwrap();
        assert_eq!(resolved.version().as_str(), "v1");
        assert!(
            resolved
                .material()
                .expose(|value| value == b"generation-one")
        );
    }

    #[test]
    fn injected_snapshot_rejects_value_and_version_from_different_generations() {
        let fixture = InjectedFixture::new();
        let projection = fixture.project_linked_generation(
            "injected://tls/runtime-key",
            "generation-one",
            b"generation-one-value",
            "v1",
        );
        fixture.create_generation("generation-two", b"generation-two-value", "v2");
        let requirement = requirement("injected://tls/runtime-key", "v1");
        replace_projection_link(&projection, "generation-two", "value");

        let error = InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [requirement])
            .unwrap_err();

        assert_eq!(error.kind(), InjectedSecretErrorKind::ChangedDuringSnapshot);
    }

    #[test]
    fn injected_snapshot_rejects_version_size_type_and_permission_violations() {
        let cases = [
            (
                Violation::VersionMismatch,
                InjectedSecretErrorKind::VersionMismatch,
            ),
            (
                Violation::MalformedVersion,
                InjectedSecretErrorKind::InvalidVersion,
            ),
            (Violation::OversizedValue, InjectedSecretErrorKind::TooLarge),
            (
                Violation::ValueIsDirectory,
                InjectedSecretErrorKind::NotRegularFile,
            ),
            (
                Violation::WritableValue,
                InjectedSecretErrorKind::UnsafePermissions,
            ),
            (
                Violation::WorldReadableValue,
                InjectedSecretErrorKind::UnsafePermissions,
            ),
            (
                Violation::WritableVersion,
                InjectedSecretErrorKind::UnsafePermissions,
            ),
            (
                Violation::WritableDirectory,
                InjectedSecretErrorKind::UnsafePermissions,
            ),
            (
                Violation::UnreadableValue,
                InjectedSecretErrorKind::Unreadable,
            ),
        ];

        for (violation, expected_kind) in cases {
            let fixture = InjectedFixture::new();
            let projection = fixture.project("injected://service/key", b"value", "v1");
            violation.apply(&projection);
            let error = InjectedSecretSnapshot::load_from_root_for_test(
                fixture.root(),
                [requirement("injected://service/key", "v1")],
            )
            .unwrap_err();
            assert_eq!(error.kind(), expected_kind, "case {violation:?}");
            assert!(!format!("{error:?}").contains("value"));
        }
    }

    #[test]
    fn injected_snapshot_rejects_missing_duplicate_and_unsafe_root_inputs() {
        let fixture = InjectedFixture::new();
        let required = requirement("injected://service/key", "v1");
        let missing =
            InjectedSecretSnapshot::load_from_root_for_test(fixture.root(), [required.clone()])
                .unwrap_err();
        assert_eq!(missing.kind(), InjectedSecretErrorKind::Missing);

        fixture.project("injected://service/key", b"secret", "v1");
        let duplicate = InjectedSecretSnapshot::load_from_root_for_test(
            fixture.root(),
            [required.clone(), required],
        )
        .unwrap_err();
        assert_eq!(
            duplicate.kind(),
            InjectedSecretErrorKind::DuplicateReference
        );

        fs::set_permissions(fixture.root(), fs::Permissions::from_mode(0o775)).unwrap();
        let unsafe_root = InjectedSecretSnapshot::load_from_root_for_test(
            fixture.root(),
            [requirement("injected://service/key", "v1")],
        )
        .unwrap_err();
        assert_eq!(
            unsafe_root.kind(),
            InjectedSecretErrorKind::UnsafePermissions
        );
        assert!(unsafe_root.reference().is_none());
    }

    #[test]
    fn root_identity_loading_reuses_contained_injected_projection_rules() {
        let fixture = InjectedFixture::new();
        fixture.project_linked(
            "injected://ahri-tre/root-identity",
            b"AGE-SECRET-KEY-TEST",
            "v1",
        );

        let material = crate::load_root_identity_material_from_root(fixture.root()).unwrap();
        material.expose(|value| assert_eq!(value, b"AGE-SECRET-KEY-TEST"));
    }

    fn requirement(uri: &str, version: &str) -> InjectedSecretRequirement {
        InjectedSecretRequirement::new(
            InjectedSecretReference::from_str(uri).unwrap(),
            InjectedSecretVersion::from_str(version).unwrap(),
        )
    }

    static NEXT_FIXTURE: AtomicU64 = AtomicU64::new(1);

    struct InjectedFixture {
        base: PathBuf,
        root: PathBuf,
    }

    impl InjectedFixture {
        fn new() -> Self {
            let id = NEXT_FIXTURE.fetch_add(1, Ordering::Relaxed);
            let base =
                std::env::temp_dir().join(format!("ahri-tre-secrets-{}-{id}", std::process::id()));
            fs::create_dir(&base).unwrap();
            let root = base.join("run-secrets");
            fs::create_dir(&root).unwrap();
            Self { base, root }
        }

        fn base(&self) -> &Path {
            &self.base
        }

        fn root(&self) -> &Path {
            &self.root
        }

        fn project(&self, uri: &str, value: &[u8], version: &str) -> PathBuf {
            let reference = InjectedSecretReference::from_str(uri).unwrap();
            let directory = reference
                .segments()
                .fold(self.root.clone(), |path, segment| path.join(segment));
            fs::create_dir_all(&directory).unwrap();
            write_protected(&directory.join("value"), value, 0o400);
            write_protected(&directory.join("version"), version.as_bytes(), 0o444);
            directory
        }

        fn project_linked(&self, uri: &str, value: &[u8], version: &str) -> PathBuf {
            let projection = self.project(uri, b"placeholder", "placeholder");
            let data = self.root.join("projection-data");
            fs::create_dir(&data).unwrap();
            write_protected(&data.join("value"), value, 0o400);
            write_protected(&data.join("version"), version.as_bytes(), 0o444);
            fs::remove_file(projection.join("value")).unwrap();
            fs::remove_file(projection.join("version")).unwrap();
            let relative_data = Path::new("../../projection-data");
            symlink(relative_data.join("value"), projection.join("value")).unwrap();
            symlink(relative_data.join("version"), projection.join("version")).unwrap();
            projection
        }

        fn project_linked_generation(
            &self,
            uri: &str,
            generation: &str,
            value: &[u8],
            version: &str,
        ) -> PathBuf {
            let projection = self.project(uri, b"placeholder", "placeholder");
            self.create_generation(generation, value, version);
            replace_projection_links(&projection, generation);
            projection
        }

        fn create_generation(&self, generation: &str, value: &[u8], version: &str) {
            let data = self.root.join(generation);
            fs::create_dir(&data).unwrap();
            write_protected(&data.join("value"), value, 0o400);
            write_protected(&data.join("version"), version.as_bytes(), 0o444);
        }
    }

    impl Drop for InjectedFixture {
        fn drop(&mut self) {
            fs::remove_dir_all(&self.base).unwrap();
        }
    }

    fn write_protected(path: &Path, value: &[u8], mode: u32) {
        if path.exists() {
            fs::set_permissions(path, fs::Permissions::from_mode(0o600)).unwrap();
        }
        fs::write(path, value).unwrap();
        fs::set_permissions(path, fs::Permissions::from_mode(mode)).unwrap();
    }

    fn replace_projection_links(projection: &Path, generation: &str) {
        for name in ["value", "version"] {
            replace_projection_link(projection, generation, name);
        }
    }

    fn replace_projection_link(projection: &Path, generation: &str, name: &str) {
        let path = projection.join(name);
        if path.exists() || path.symlink_metadata().is_ok() {
            fs::remove_file(&path).unwrap();
        }
        symlink(Path::new("../..").join(generation).join(name), path).unwrap();
    }

    #[derive(Debug, Clone, Copy)]
    enum Violation {
        VersionMismatch,
        MalformedVersion,
        OversizedValue,
        ValueIsDirectory,
        WritableValue,
        WorldReadableValue,
        WritableVersion,
        WritableDirectory,
        UnreadableValue,
    }

    impl Violation {
        fn apply(self, projection: &Path) {
            match self {
                Self::VersionMismatch => write_protected(&projection.join("version"), b"v2", 0o444),
                Self::MalformedVersion => {
                    write_protected(&projection.join("version"), b"V1", 0o444)
                }
                Self::OversizedValue => write_protected(
                    &projection.join("value"),
                    &vec![b'x'; MAX_SECRET_MATERIAL_BYTES + 1],
                    0o400,
                ),
                Self::ValueIsDirectory => {
                    fs::remove_file(projection.join("value")).unwrap();
                    fs::create_dir(projection.join("value")).unwrap();
                }
                Self::WritableValue => {
                    fs::set_permissions(
                        projection.join("value"),
                        fs::Permissions::from_mode(0o600),
                    )
                    .unwrap();
                }
                Self::WorldReadableValue => {
                    fs::set_permissions(
                        projection.join("value"),
                        fs::Permissions::from_mode(0o404),
                    )
                    .unwrap();
                }
                Self::WritableVersion => {
                    fs::set_permissions(
                        projection.join("version"),
                        fs::Permissions::from_mode(0o464),
                    )
                    .unwrap();
                }
                Self::WritableDirectory => {
                    fs::set_permissions(projection, fs::Permissions::from_mode(0o775)).unwrap();
                }
                Self::UnreadableValue => {
                    fs::set_permissions(
                        projection.join("value"),
                        fs::Permissions::from_mode(0o000),
                    )
                    .unwrap();
                }
            }
        }
    }
}