harn-vm 0.10.153

//! Session-scoped environment policy and grants.
//!
//! Every launched session has exactly one policy:
//!
//! - [`EnvironmentPolicyKind::Inherited`] preserves a launch-time snapshot.
//! - [`EnvironmentPolicyKind::Isolated`] admits runtime essentials only.
//! - [`EnvironmentPolicyKind::Granted`] adds declared grants to those
//!   essentials.
//!
//! A child receives the parent's resolved object and may call
//! [`SessionEnvironment::narrow`]; it never rereads the ambient host
//! environment or gains authority its parent did not have.
//!
//! # Ownership boundary
//!
//! The launcher (e.g. the Burin CLI) parses its own `--grant name=spec`
//! strings **at its boundary** and hands harn a typed, value-free
//! [`GrantSpec`] set — carried in the session/ACP config. harn does not parse
//! flag strings. harn owns the typed contract: [`GrantSpec`] in,
//! [`SessionGrant`]/[`SessionEnvironment`] resolution, [`GrantReceipt`] schema,
//! and policy enforcement.
//!
//! A [`GrantSpec`] is value-free: an `env:` source names the launcher variable
//! (not its value); a `secret_store` source is an account/key *pointer*. So a
//! spec is safe to serialize into a session config. The resolved
//! [`SessionGrant`] may hold a snapshotted secret value, so it is deliberately
//! **not** `Serialize` and never lands in a record — only [`GrantReceipt`]
//! ({name, source_kind, exposed_as_env, for_command, exposed_to}) is
//! persisted, and it omits even the secret pointer.
//!
//! An exposed grant reaches one [`GrantAudience`]: the whole session, one
//! command (`for_command`), or Harn's own process only (`in_process`). The
//! in-process audience is how a host lets `llm_call` authenticate without
//! placing the credential, or a secret reference to it, in any child's
//! environment.
//!
//! Two non-leakage properties are enforced by the type system:
//!
//!   * The value-bearing types ([`SessionGrant`], [`SessionEnvironment`], and the
//!     private `ResolvedRef`) are not `Serialize`. The compiler refuses to
//!     serialize a type that can hold a secret, so a record cannot leak one.
//!   * An `env:` source is snapshotted at launch, so the child never reads the
//!     launcher's live environment; a later env mutation does not change what
//!     the session sees.
//!
//! Materializing a `secret_store` pointer into a value happens through the
//! embedder's `resolve_secret` closure (backed by the `secret_store` facade),
//! so this crate takes no dependency on the hostlib that registers it.

use std::collections::{BTreeMap, BTreeSet};
use std::fmt;

use serde::{Deserialize, Serialize};

/// Where a granted value originates. Recorded in receipts as a stable
/// string; never carries the value itself.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum GrantSource {
    /// Snapshotted from a launcher environment variable at launch time.
    Env,
    /// A pointer into the `secret_store` facade, resolved on use.
    SecretStore,
    /// A value stated outright by the declaration.
    Literal,
}

impl GrantSource {
    /// Stable wire string used in receipts and diagnostics.
    pub fn as_str(self) -> &'static str {
        match self {
            GrantSource::Env => "env",
            GrantSource::SecretStore => "secret_store",
            GrantSource::Literal => "literal",
        }
    }
}

/// The value-free source of a grant, as declared in the session config. An
/// `Env` source names a launcher variable (not its value); a `SecretStore`
/// source is an account/key pointer. Both are safe to serialize.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GrantSourceSpec {
    /// Snapshot the named launcher environment variable at launch.
    Env { var: String },
    /// A `secret_store` account/key pointer, resolved lazily on exposure.
    SecretStore { account: String, key: String },
    /// A value the declaration states outright, used verbatim.
    ///
    /// The other two sources name where a value will come from. This one is
    /// the value, which is why it exists: a host sometimes has to say what a
    /// child should hold rather than hope the launcher holds it. The case
    /// that forced it is the empty string, because several developer tools
    /// read an empty variable as an explicit "off" that differs from the
    /// variable being absent, and a snapshot source cannot express "off" for
    /// a name the launcher has never set.
    ///
    /// Not a secret channel. A literal is written in the declaration and
    /// travels with it, so it is exactly as visible as the declaration is.
    /// Credentials belong in [`GrantSourceSpec::SecretStore`], which stays a
    /// pointer and stays revocable, and a literal that states a secret
    /// reference is refused at launch rather than trusted to a reader.
    Literal { value: String },
}

impl GrantSourceSpec {
    fn kind(&self) -> GrantSource {
        match self {
            GrantSourceSpec::Env { .. } => GrantSource::Env,
            GrantSourceSpec::SecretStore { .. } => GrantSource::SecretStore,
            GrantSourceSpec::Literal { .. } => GrantSource::Literal,
        }
    }
}

/// Which readers an exposed grant reaches.
///
/// An exposed grant has exactly one of three audiences:
///
/// | Declaration | In-process readers | Spawned children |
/// |---|---|---|
/// | `expose_to: session` (default), no `for_command` | yes | every spawn |
/// | `expose_to: session` with `for_command` | no | spawns of that command |
/// | `expose_to: in_process` | yes | none |
///
/// In-process readers are Harn's own process: provider credentials and
/// provider configuration for `llm_call`, and `harness.env`. The
/// `in_process` audience exists so a host can let Harn authenticate its own
/// model calls without handing the credential, or a secret reference that
/// resolves to it, to every command the session runs.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GrantAudience {
    /// In-process readers and spawned children (narrowed by `for_command`).
    #[default]
    Session,
    /// In-process readers only. Never part of any child environment.
    InProcess,
}

impl GrantAudience {
    /// Whether this is the default audience; used to keep the default off
    /// the wire so existing specs and receipts stay byte-identical.
    pub fn is_session(&self) -> bool {
        matches!(self, GrantAudience::Session)
    }
}

/// A single grant as declared by the launcher in the session config. Typed and
/// value-free: harn receives this already-structured (the launcher did any
/// string parsing at its own boundary) and validates/resolves it once, here.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GrantSpec {
    /// Logical grant name used in receipts and diagnostics.
    pub name: String,
    /// Where the credential comes from.
    pub source: GrantSourceSpec,
    /// The target process-env variable to expose the value as, if any. `None`
    /// (the default) means the grant is not exposed to `process.exec`. This is
    /// the sole place the exposure default lives.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expose_as_env: Option<String>,
    /// When set with [`Self::expose_as_env`], bind the exposure to spawned
    /// commands whose executable basename matches this value (for example
    /// `gh` for `/usr/bin/gh`). Omitted means session-scoped exposure:
    /// `harness.env`, providers, and every spawned command see the variable.
    /// Command-scoped grants are invisible in-process by construction — harn's
    /// own `llm_call` is not an exec (harn#5549).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub for_command: Option<String>,
    /// Which readers the exposure reaches. [`GrantAudience::InProcess`]
    /// requires [`Self::expose_as_env`] and rejects [`Self::for_command`]; see
    /// [`GrantAudience`] for the full table.
    #[serde(default, skip_serializing_if = "GrantAudience::is_session")]
    pub expose_to: GrantAudience,
}

impl GrantSpec {
    /// Validate the declared shape (non-empty name/fields) and resolve against
    /// the launcher environment, snapshotting an `env:` source so the child
    /// never reads the live environment. A `secret_store` source is carried
    /// through as a pointer, resolved lazily on exposure.
    fn resolve(
        self,
        env_lookup: &dyn Fn(&str) -> Option<String>,
    ) -> Result<SessionGrant, EnvironmentPolicyError> {
        let name = self.name.trim();
        if name.is_empty() {
            return Err(EnvironmentPolicyError::EmptyName);
        }
        if let Some(var) = self.expose_as_env.as_deref() {
            if var.trim().is_empty() {
                return Err(EnvironmentPolicyError::EmptyExposeVar {
                    name: name.to_string(),
                });
            }
        }
        let for_command = match self.for_command.as_deref().map(str::trim) {
            None | Some("") if self.for_command.is_some() => {
                return Err(EnvironmentPolicyError::EmptyForCommand {
                    name: name.to_string(),
                });
            }
            None => None,
            Some(command) => {
                if self
                    .expose_as_env
                    .as_deref()
                    .map(str::trim)
                    .is_none_or(|v| v.is_empty())
                {
                    return Err(EnvironmentPolicyError::ForWithoutExpose {
                        name: name.to_string(),
                    });
                }
                if command.contains('/') || command.contains('\\') {
                    return Err(EnvironmentPolicyError::InvalidForCommand {
                        name: name.to_string(),
                        command: command.to_string(),
                    });
                }
                Some(command.to_string())
            }
        };
        if self.expose_to == GrantAudience::InProcess {
            if self
                .expose_as_env
                .as_deref()
                .map(str::trim)
                .is_none_or(|v| v.is_empty())
            {
                return Err(EnvironmentPolicyError::InProcessWithoutExpose {
                    name: name.to_string(),
                });
            }
            if for_command.is_some() {
                return Err(EnvironmentPolicyError::InProcessWithCommand {
                    name: name.to_string(),
                });
            }
        }
        let source_kind = self.source.kind();
        let source_spec = self.source.clone();
        let resolved_ref = match self.source {
            GrantSourceSpec::Env { var } => {
                let var = var.trim();
                if var.is_empty() {
                    return Err(EnvironmentPolicyError::EmptyEnvVar {
                        name: name.to_string(),
                    });
                }
                let value = env_lookup(var).ok_or_else(|| EnvironmentPolicyError::MissingEnv {
                    name: name.to_string(),
                    var: var.to_string(),
                })?;
                ResolvedRef::EnvSnapshot(value)
            }
            GrantSourceSpec::SecretStore { account, key } => {
                let (account, key) = (account.trim(), key.trim());
                if account.is_empty() || key.is_empty() {
                    return Err(EnvironmentPolicyError::EmptySecretRef {
                        name: name.to_string(),
                    });
                }
                ResolvedRef::SecretStore {
                    account: account.to_string(),
                    key: key.to_string(),
                }
            }
            GrantSourceSpec::Literal { value } => {
                // A secret reference is not a constant. The vocabulary has a
                // source for credentials and it stays a pointer, so the store
                // remains the single source of truth and the grant remains
                // revocable. A credential written here would be laundered
                // into the declaration, where it is as durable as the
                // declaration is. There is no registry of names the secret
                // vocabulary claims, so this keys on the reference scheme,
                // which is the one structural marker that exists.
                if value
                    .trim_start()
                    .starts_with(crate::secrets::SECRET_REF_SCHEME)
                {
                    return Err(EnvironmentPolicyError::LiteralSecretReference {
                        name: name.to_string(),
                    });
                }
                // Otherwise verbatim, including an empty value and including
                // surrounding whitespace. The other two sources trim because
                // they carry a NAME, where whitespace is a typo. This one
                // carries a VALUE, where whitespace may be the point, and
                // trimming would be the vocabulary quietly editing what the
                // host said.
                ResolvedRef::Literal(value)
            }
        };
        Ok(SessionGrant {
            name: name.to_string(),
            source_kind,
            source_spec,
            expose_as_env: self.expose_as_env.map(|var| var.trim().to_string()),
            for_command,
            audience: self.expose_to,
            resolved_ref,
        })
    }
}

/// The resolved backing of a grant. Private so no consumer can branch on it;
/// intentionally not `Serialize` so a snapshotted value can never leak into a
/// record.
#[derive(Clone, Debug, PartialEq, Eq)]
enum ResolvedRef {
    /// A value captured from the launcher env at launch. Held here and never
    /// re-read from the live environment.
    EnvSnapshot(String),
    /// A `secret_store` pointer, resolved to a value only on exposure. Kept as
    /// a pointer (not a snapshot) so the upstream source stays the single
    /// source of truth and the grant remains revocable.
    SecretStore { account: String, key: String },
    /// A value the declaration stated. Held as given.
    Literal(String),
}

/// A grant validated and resolved once at the launch boundary. Consumers read
/// this record; they do not re-branch on `source_kind` or re-check exposure.
///
/// Deliberately not `Serialize`: it can hold a snapshotted secret value, so it
/// must never land in a record. Use [`GrantReceipt`] for anything persisted.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SessionGrant {
    name: String,
    source_kind: GrantSource,
    source_spec: GrantSourceSpec,
    expose_as_env: Option<String>,
    for_command: Option<String>,
    audience: GrantAudience,
    resolved_ref: ResolvedRef,
}

impl SessionGrant {
    fn matches_spec(&self, spec: &GrantSpec) -> bool {
        self.name == spec.name.trim()
            && self.source_spec == spec.source
            && self.expose_as_env.as_deref() == spec.expose_as_env.as_deref().map(str::trim)
            && self.for_command.as_deref() == spec.for_command.as_deref().map(str::trim)
            && self.audience == spec.expose_to
    }
    /// The grant's logical name used in receipts and diagnostics.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Where the credential originates.
    pub fn source_kind(&self) -> GrantSource {
        self.source_kind
    }

    /// The process-env variable this grant is exposed as, if any.
    pub fn exposed_env_var(&self) -> Option<&str> {
        self.expose_as_env.as_deref()
    }

    /// The command basename this exposure is bound to, if any.
    pub fn for_command(&self) -> Option<&str> {
        self.for_command.as_deref()
    }

    /// Which readers this grant's exposure reaches.
    pub fn audience(&self) -> GrantAudience {
        self.audience
    }

    /// Whether Harn's own process (provider auth, `harness.env`) reads this
    /// grant: session-wide grants and in-process grants, never command-bound
    /// ones.
    fn reaches_in_process(&self) -> bool {
        self.for_command.is_none()
    }

    /// Whether this grant's exposure belongs in a child environment.
    ///
    /// `program` is the spawn's executable, or `None` when the caller builds a
    /// child environment without knowing it, which admits session-wide grants
    /// only. This is the single answer to "does a child see this grant";
    /// every child-environment builder asks it.
    pub fn reaches_spawn(&self, program: Option<&str>) -> bool {
        if self.audience == GrantAudience::InProcess {
            return false;
        }
        match (self.for_command.as_deref(), program) {
            (None, _) => true,
            (Some(expected), Some(program)) => command_basename(program) == expected,
            (Some(_), None) => false,
        }
    }

    /// The `(VAR, value)` pair this grant publishes, or `None` when it declared
    /// no `expose_as_env` target.
    ///
    /// This is the single place the source kind is branched on — an
    /// `EnvSnapshot` is already a value; a `secret_store` pointer is resolved
    /// here, on use, through the embedder's `resolve_secret` closure. Every
    /// exposure path goes through this one method, so a consumer never sees the
    /// source kind and the two paths cannot disagree about what a grant means.
    fn exposure(
        &self,
        resolve_secret: &dyn Fn(&str, &str) -> Option<String>,
    ) -> Option<Result<(String, String), EnvironmentPolicyError>> {
        let var = self.expose_as_env.as_ref()?;
        let value = match &self.resolved_ref {
            ResolvedRef::EnvSnapshot(value) | ResolvedRef::Literal(value) => value.clone(),
            ResolvedRef::SecretStore { account, key } => match resolve_secret(account, key) {
                Some(value) => value,
                None => {
                    return Some(Err(EnvironmentPolicyError::MissingSecret {
                        name: self.name.clone(),
                    }))
                }
            },
        };
        Some(Ok((var.clone(), value)))
    }

    /// The non-secret receipt for this grant.
    pub fn receipt(&self) -> GrantReceipt {
        GrantReceipt {
            name: self.name.clone(),
            source_kind: self.source_kind.as_str().to_string(),
            exposed_as_env: self.expose_as_env.clone(),
            for_command: self.for_command.clone(),
            exposed_to: self.audience,
        }
    }
}

/// Executable basename used to match a `for_command` grant binding.
///
/// `/usr/bin/gh` and `gh` both yield `gh`. Path separators of either style are
/// recognized so a Windows-style `C:\Tools\gh.exe` still matches `for=gh` when
/// compared on a Unix host (and vice versa). A trailing `.exe` / `.bat` /
/// `.cmd` / `.com` suffix is stripped so `gh.exe` matches `for=gh`.
pub fn command_basename(program: &str) -> &str {
    let name = program
        .rsplit(['/', '\\'])
        .next()
        .filter(|name| !name.is_empty())
        .unwrap_or(program);
    strip_windows_executable_suffix(name)
}

fn strip_windows_executable_suffix(name: &str) -> &str {
    const SUFFIXES: &[&str] = &[".exe", ".bat", ".cmd", ".com"];
    for suffix in SUFFIXES {
        let Some(stem_len) = name.len().checked_sub(suffix.len()).filter(|len| *len > 0) else {
            continue;
        };
        if let Some((stem, tail)) = name.split_at_checked(stem_len) {
            if tail.eq_ignore_ascii_case(suffix) {
                return stem;
            }
        }
    }
    name
}

/// Which environment policy a session launches under. This is a typed launch
/// input, not an emergent property of which flags were passed.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EnvironmentPolicyKind {
    /// Preserve a launch-time snapshot of the launcher's environment.
    #[default]
    Inherited,
    /// Admit only non-secret runtime essentials. Grants are forbidden.
    Isolated,
    /// Admit runtime essentials plus the declared grant set.
    Granted,
}

impl EnvironmentPolicyKind {
    pub fn as_str(self) -> &'static str {
        match self {
            EnvironmentPolicyKind::Inherited => "inherited",
            EnvironmentPolicyKind::Isolated => "isolated",
            EnvironmentPolicyKind::Granted => "granted",
        }
    }
}

/// A launched session's resolved environment.
///
/// Not `Serialize` (its grants may hold snapshotted values); serialize
/// [`SessionEnvironment::receipts`] instead.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SessionEnvironment {
    kind: EnvironmentPolicyKind,
    launcher_snapshot: BTreeMap<String, String>,
    grants: Vec<SessionGrant>,
}

impl SessionEnvironment {
    /// Capture the default policy at a session launch boundary.
    pub fn inherited() -> Self {
        Self::launch(EnvironmentPolicyKind::Inherited, Vec::new(), &|name| {
            std::env::var(name).ok()
        })
        .expect("the inherited policy has no fallible grant configuration")
    }

    /// Launch an environment from the config's declared grant specs, resolving each
    /// against the launcher environment.
    ///
    /// An isolated policy **rejects any grant at launch** — isolation is an
    /// enforced structural property, not an assertion made after the fact. A
    /// granted policy resolves and carries the declared grant set.
    pub fn launch(
        kind: EnvironmentPolicyKind,
        specs: Vec<GrantSpec>,
        env_lookup: &dyn Fn(&str) -> Option<String>,
    ) -> Result<Self, EnvironmentPolicyError> {
        let mut launcher_snapshot = capture_process_environment();
        for name in super::environment_policy::ENV_ALLOWLIST {
            if let Some(value) = env_lookup(name) {
                insert_env_value(&mut launcher_snapshot, name, value);
            }
        }
        Self::launch_from_snapshot(kind, specs, launcher_snapshot, env_lookup)
    }

    /// Resolve a session from one authoritative launcher snapshot.
    ///
    /// `env_lookup` exists for embedders that supply a typed environment
    /// source. Production callers normally pass a lookup over the same
    /// snapshot, while tests can provide a small deterministic map.
    pub fn launch_from_snapshot(
        kind: EnvironmentPolicyKind,
        specs: Vec<GrantSpec>,
        launcher_snapshot: BTreeMap<String, String>,
        env_lookup: &dyn Fn(&str) -> Option<String>,
    ) -> Result<Self, EnvironmentPolicyError> {
        if !matches!(kind, EnvironmentPolicyKind::Granted) && !specs.is_empty() {
            return Err(EnvironmentPolicyError::PolicyForbidsGrants {
                policy: kind,
                attempted: specs.len(),
            });
        }
        validate_unique_specs(&specs)?;
        let grants = specs
            .into_iter()
            .map(|spec| spec.resolve(env_lookup))
            .collect::<Result<Vec<_>, _>>()?;
        let launcher_snapshot = if matches!(kind, EnvironmentPolicyKind::Inherited) {
            launcher_snapshot
        } else {
            launcher_snapshot
                .into_iter()
                .filter(|(name, _)| super::environment_policy::allowlist_admits(name))
                .collect()
        };
        Ok(SessionEnvironment {
            kind,
            launcher_snapshot,
            grants,
        })
    }

    /// An isolated environment with no grants.
    pub fn isolated() -> Self {
        Self::launch(EnvironmentPolicyKind::Isolated, Vec::new(), &|name| {
            std::env::var(name).ok()
        })
        .expect("the isolated policy has no fallible grant configuration")
    }

    pub fn kind(&self) -> EnvironmentPolicyKind {
        self.kind
    }

    pub fn is_isolated(&self) -> bool {
        matches!(self.kind, EnvironmentPolicyKind::Isolated)
    }

    /// Whether provider SDKs may use platform-managed ambient discovery such
    /// as AWS shared config, metadata services, or application-default
    /// credentials.
    pub fn allows_implicit_discovery(&self) -> bool {
        matches!(self.kind, EnvironmentPolicyKind::Inherited)
    }

    /// Derive a child session without allowing it to gain environment
    /// authority that its parent did not have.
    pub fn narrow(
        &self,
        requested: EnvironmentPolicyKind,
        specs: Vec<GrantSpec>,
    ) -> Result<Self, EnvironmentPolicyError> {
        match (self.kind, requested) {
            (EnvironmentPolicyKind::Inherited, EnvironmentPolicyKind::Inherited)
                if specs.is_empty() =>
            {
                Ok(self.clone())
            }
            (EnvironmentPolicyKind::Inherited, EnvironmentPolicyKind::Isolated)
                if specs.is_empty() =>
            {
                Ok(Self {
                    kind: requested,
                    launcher_snapshot: self.launcher_snapshot.clone(),
                    grants: Vec::new(),
                })
            }
            (EnvironmentPolicyKind::Inherited, EnvironmentPolicyKind::Granted) => {
                if let Some(spec) = specs
                    .iter()
                    .find(|spec| matches!(spec.source, GrantSourceSpec::SecretStore { .. }))
                {
                    return Err(EnvironmentPolicyError::ChildPolicyExceedsParent {
                        parent: self.kind,
                        requested,
                        offending_grant: Some(spec.name.trim().to_string()),
                        detail: "an inherited parent can grant only values in its launch-time environment snapshot; secret-store authority must be granted to the parent first".to_string(),
                    });
                }
                let snapshot = self.launcher_snapshot.clone();
                Self::launch_from_snapshot(requested, specs, snapshot.clone(), &|name| {
                    snapshot.get(name).cloned()
                })
            }
            (EnvironmentPolicyKind::Granted, EnvironmentPolicyKind::Isolated)
                if specs.is_empty() =>
            {
                Ok(Self {
                    kind: requested,
                    launcher_snapshot: self.launcher_snapshot.clone(),
                    grants: Vec::new(),
                })
            }
            (EnvironmentPolicyKind::Granted, EnvironmentPolicyKind::Granted) => {
                validate_unique_specs(&specs)?;
                let mut grants = Vec::with_capacity(specs.len());
                for spec in &specs {
                    let Some(grant) = self.grants.iter().find(|grant| grant.matches_spec(spec))
                    else {
                        return Err(EnvironmentPolicyError::ChildPolicyExceedsParent {
                            parent: self.kind,
                            requested,
                            offending_grant: Some(spec.name.trim().to_string()),
                            detail: format!(
                                "grant '{}' is not an unchanged subset of the parent grants",
                                spec.name.trim()
                            ),
                        });
                    };
                    grants.push(grant.clone());
                }
                Ok(Self {
                    kind: requested,
                    launcher_snapshot: self.launcher_snapshot.clone(),
                    grants,
                })
            }
            _ => Err(EnvironmentPolicyError::ChildPolicyExceedsParent {
                parent: self.kind,
                requested,
                offending_grant: specs.first().map(|spec| spec.name.trim().to_string()),
                detail:
                    "a child may keep or reduce its parent's environment access, never widen it"
                        .to_string(),
            }),
        }
    }

    /// The launcher's value for `name`, matched the way the host platform
    /// matches environment names.
    ///
    /// Windows environment names are case-insensitive, and the case a parent
    /// reports is not the case an allowlist is written in: the variable this
    /// codebase calls `PATH` arrives from a Windows parent spelled `Path`.
    /// An exact map lookup therefore misses it, and a child inherits no
    /// search path at all while every name in the allowlist still looks
    /// admitted. Fold case on Windows so the allowlist means the same thing
    /// there that it means on POSIX, where names are case-sensitive and the
    /// exact lookup is the correct one.
    pub(crate) fn launcher_value(&self, name: &str) -> Option<&str> {
        if let Some(value) = self.launcher_snapshot.get(name) {
            return Some(value.as_str());
        }
        if cfg!(windows) {
            return self
                .launcher_snapshot
                .iter()
                .find(|(key, _)| key.eq_ignore_ascii_case(name))
                .map(|(_, value)| value.as_str());
        }
        None
    }

    pub(crate) fn launcher_snapshot(&self) -> &BTreeMap<String, String> {
        &self.launcher_snapshot
    }

    /// The resolved grants. Empty for an isolated policy, always.
    pub fn grants(&self) -> &[SessionGrant] {
        &self.grants
    }

    /// The non-secret receipts recorded on the session run-record. Empty for an
    /// isolated policy, which makes `grants: []` a checked property.
    pub fn receipts(&self) -> Vec<GrantReceipt> {
        self.grants.iter().map(SessionGrant::receipt).collect()
    }

    /// Every environment variable name a child of this session can see, sorted
    /// and deduplicated. Names only; a value never appears here.
    ///
    /// This answers the question a reader of a run record actually has, which
    /// the policy kind alone does not: *what did this run hand to the
    /// processes that executed tool calls?* `Isolated` and `Granted` are
    /// already allowlist-filtered in the snapshot, so this is that filtered
    /// set plus anything a grant exposes. `Inherited` returns the launcher's
    /// whole set, which is the honest answer for a session that asked to
    /// inherit it, and is usually the moment a reader notices how large it is.
    ///
    /// Command-bound grants are included: a name reachable by some child is
    /// exposed by this run, and a receipt that hid it behind the binding
    /// would understate the run's authority.
    ///
    /// In-process grants are excluded: no child can see them, and listing
    /// them here would claim a child authority the run never had. Their
    /// receipts (`exposed_to: in_process`) record that Harn itself held them.
    pub fn admitted_environment_names(&self) -> Vec<String> {
        let mut names: Vec<String> = self.launcher_snapshot.keys().cloned().collect();
        for grant in &self.grants {
            if grant.audience == GrantAudience::InProcess {
                continue;
            }
            if let Some(var) = grant.expose_as_env.clone() {
                names.push(var);
            }
        }
        names.sort();
        names.dedup();
        names
    }

    /// Materialize the child environment overlay for a spawn whose executable
    /// is not known: the `(VAR, value)` pairs for every session-wide grant.
    /// Empty for an isolated policy.
    ///
    /// Callers receive uniform pairs and never see the source kind;
    /// [`SessionGrant::exposure`] owns that branch.
    ///
    /// Command-bound grants are added only by
    /// [`env_exposure_for_command`](Self::env_exposure_for_command)
    /// (harn#5549). In-process grants are never part of a child overlay.
    pub fn env_exposure(
        &self,
        resolve_secret: &dyn Fn(&str, &str) -> Option<String>,
    ) -> Result<Vec<(String, String)>, EnvironmentPolicyError> {
        self.child_exposure(None, resolve_secret)
    }

    /// Materialize the environment overlay for one spawn of `program`: every
    /// session-wide grant, plus every command-bound grant whose `for_command`
    /// matches [`command_basename`] of `program`. In-process grants are never
    /// included.
    pub fn env_exposure_for_command(
        &self,
        program: &str,
        resolve_secret: &dyn Fn(&str, &str) -> Option<String>,
    ) -> Result<Vec<(String, String)>, EnvironmentPolicyError> {
        self.child_exposure(Some(program), resolve_secret)
    }

    fn child_exposure(
        &self,
        program: Option<&str>,
        resolve_secret: &dyn Fn(&str, &str) -> Option<String>,
    ) -> Result<Vec<(String, String)>, EnvironmentPolicyError> {
        self.grants
            .iter()
            .filter(|grant| grant.reaches_spawn(program))
            .filter_map(|grant| grant.exposure(resolve_secret))
            .collect()
    }

    /// The value Harn's own process reads under a single environment
    /// variable, or `None` if no in-process-visible grant targets it.
    ///
    /// This is the in-process reader behind harn's provider-credential lookup
    /// and `harness.env`. Session-wide and in-process grants are visible here;
    /// command-bound grants are not, because they are not in-process
    /// credentials. It resolves *only* the grant that targets `var`, which
    /// matters for a `secret_store` grant: probing an unrelated variable must
    /// not reach the secret store, and one unresolvable grant must not mask an
    /// unrelated credential. Launch validation guarantees at most one matching
    /// grant.
    pub fn env_exposure_for(
        &self,
        var: &str,
        resolve_secret: &dyn Fn(&str, &str) -> Option<String>,
    ) -> Result<Option<String>, EnvironmentPolicyError> {
        let Some(grant) = self.grants.iter().find(|grant| {
            grant.reaches_in_process() && grant.expose_as_env.as_deref() == Some(var)
        }) else {
            return Ok(None);
        };
        grant
            .exposure(resolve_secret)
            .transpose()
            .map(|pair| pair.map(|(_, value)| value))
    }
}

fn capture_process_environment() -> BTreeMap<String, String> {
    std::env::vars_os()
        .filter_map(|(name, value)| Some((name.into_string().ok()?, value.into_string().ok()?)))
        .collect()
}

/// Insert `name=value` the way Windows would: a name that exists under
/// different casing (`capture_process_environment` seeds OS casing `Path`;
/// `ENV_ALLOWLIST`'s re-assert loop right after it uses POSIX casing
/// `PATH`) is updated in place, not duplicated. `Inherited` hands this map
/// to a child verbatim, so an un-deduped snapshot leaks the duplicate.
fn insert_env_value_case_insensitive(
    map: &mut BTreeMap<String, String>,
    name: &str,
    value: String,
) {
    let existing_key = map
        .keys()
        .find(|key| key.eq_ignore_ascii_case(name))
        .cloned();
    map.insert(existing_key.unwrap_or_else(|| name.to_string()), value);
}

/// Case-insensitive on Windows, plain elsewhere: POSIX treats `PATH` and
/// `Path` as unrelated variables, so folding them there is the bug.
fn insert_env_value(map: &mut BTreeMap<String, String>, name: &str, value: String) {
    if cfg!(windows) {
        insert_env_value_case_insensitive(map, name, value);
    } else {
        map.insert(name.to_string(), value);
    }
}

fn validate_unique_specs(specs: &[GrantSpec]) -> Result<(), EnvironmentPolicyError> {
    let mut names = BTreeSet::new();
    let mut targets = BTreeSet::new();
    for spec in specs {
        let name = spec.name.trim();
        if !name.is_empty() && !names.insert(name) {
            return Err(EnvironmentPolicyError::DuplicateGrant {
                name: name.to_string(),
            });
        }
        if let Some(target) = spec.expose_as_env.as_deref().map(str::trim) {
            if !target.is_empty() && !targets.insert(target) {
                return Err(EnvironmentPolicyError::DuplicateExposureTarget {
                    target: target.to_string(),
                });
            }
        }
    }
    Ok(())
}

/// A non-secret record of a grant, safe to persist on a session run-record.
///
/// Carries the grant name, source kind, optional environment target, optional
/// command binding, and audience — never the value or a reversible source
/// reference. `secret_store` account/key pointers are intentionally omitted.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GrantReceipt {
    pub name: String,
    pub source_kind: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exposed_as_env: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub for_command: Option<String>,
    /// `in_process` when no child could see the exposure. Omitted for the
    /// default session audience, so a record written before audiences
    /// existed reads back as what it was.
    #[serde(default, skip_serializing_if = "GrantAudience::is_session")]
    pub exposed_to: GrantAudience,
}

impl GrantReceipt {
    /// The environment name this grant put into some child's environment,
    /// or `None` when it exposed nothing to children.
    pub fn child_visible_env(&self) -> Option<&str> {
        match self.exposed_to {
            GrantAudience::Session => self.exposed_as_env.as_deref(),
            GrantAudience::InProcess => None,
        }
    }
}

/// Errors raised while validating, resolving, or enforcing session grants. All
/// are launch-boundary failures; none carries a secret value.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum EnvironmentPolicyError {
    /// A grant spec had an empty name.
    EmptyName,
    /// An `env` source named an empty variable.
    EmptyEnvVar { name: String },
    /// A `literal` source stated a secret reference as its value. Credentials
    /// belong in a `secret_store` source, which stays a revocable pointer.
    LiteralSecretReference { name: String },
    /// A `secret_store` source named an empty account or key.
    EmptySecretRef { name: String },
    /// An `expose_as_env` target was an empty variable name.
    EmptyExposeVar { name: String },
    /// A `for_command` binding was an empty command basename.
    EmptyForCommand { name: String },
    /// A `for_command` binding was declared without `expose_as_env`.
    ForWithoutExpose { name: String },
    /// A `for_command` binding contained a path separator; only a basename is
    /// accepted.
    InvalidForCommand { name: String, command: String },
    /// An `in_process` grant declared no `expose_as_env` name for Harn's own
    /// readers to find it under.
    InProcessWithoutExpose { name: String },
    /// An `in_process` grant also declared `for_command`, which names a child
    /// audience the in-process scope never reaches.
    InProcessWithCommand { name: String },
    /// An `env` source referenced a variable absent from the launcher env.
    MissingEnv { name: String, var: String },
    /// A grant was declared on a policy that does not accept grants.
    PolicyForbidsGrants {
        policy: EnvironmentPolicyKind,
        attempted: usize,
    },
    /// More than one grant used the same logical name.
    DuplicateGrant { name: String },
    /// More than one grant targeted the same environment variable.
    DuplicateExposureTarget { target: String },
    /// A child requested more environment authority than its parent.
    ChildPolicyExceedsParent {
        parent: EnvironmentPolicyKind,
        requested: EnvironmentPolicyKind,
        offending_grant: Option<String>,
        detail: String,
    },
    /// A `secret_store` grant could not be resolved on exposure.
    MissingSecret { name: String },
}

impl fmt::Display for EnvironmentPolicyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            EnvironmentPolicyError::EmptyName => write!(
                f,
                "[environment_policy.empty_grant_name] grant spec has an empty name"
            ),
            EnvironmentPolicyError::LiteralSecretReference { name } => {
                write!(
                    f,
                    "[environment_policy.literal_secret_reference] grant '{name}' literal source states a secret reference; declare it as a secret_store source instead"
                )
            }
            EnvironmentPolicyError::EmptyEnvVar { name } => {
                write!(
                    f,
                    "[environment_policy.empty_source_variable] grant '{name}' env source names an empty variable"
                )
            }
            EnvironmentPolicyError::EmptySecretRef { name } => {
                write!(
                    f,
                    "[environment_policy.empty_secret_reference] grant '{name}' secret source names an empty account/key"
                )
            }
            EnvironmentPolicyError::EmptyExposeVar { name } => {
                write!(
                    f,
                    "[environment_policy.empty_exposure_target] grant '{name}' expose target is an empty variable"
                )
            }
            EnvironmentPolicyError::EmptyForCommand { name } => {
                write!(
                    f,
                    "[environment_policy.empty_for_command] grant '{name}' for_command binding is empty; name the command basename (for example 'gh')"
                )
            }
            EnvironmentPolicyError::ForWithoutExpose { name } => {
                write!(
                    f,
                    "[environment_policy.for_without_expose] grant '{name}' declares for_command without expose_as_env; command binding only applies to an exposed environment variable"
                )
            }
            EnvironmentPolicyError::InvalidForCommand { name, command } => {
                write!(
                    f,
                    "[environment_policy.invalid_for_command] grant '{name}' for_command '{command}' must be a command basename, not a path"
                )
            }
            EnvironmentPolicyError::InProcessWithoutExpose { name } => write!(
                f,
                "[environment_policy.in_process_without_expose] grant '{name}' declares expose_to in_process without expose_as_env; name the variable Harn's own readers should find it under"
            ),
            EnvironmentPolicyError::InProcessWithCommand { name } => write!(
                f,
                "[environment_policy.in_process_with_command] grant '{name}' declares expose_to in_process with for_command; an in-process grant reaches no spawned command, so remove one of the two"
            ),
            EnvironmentPolicyError::MissingEnv { name, var } => write!(
                f,
                "[environment_policy.source_variable_missing] grant '{name}' env source variable '{var}' is not set in the launcher environment; set it before launch or choose another source"
            ),
            EnvironmentPolicyError::PolicyForbidsGrants { policy, attempted } => write!(
                f,
                "[environment_policy.grants_forbidden] environment policy '{}' forbids grants, but {attempted} were declared; use 'granted' or remove the grants",
                policy.as_str()
            ),
            EnvironmentPolicyError::DuplicateGrant { name } => write!(
                f,
                "[environment_policy.duplicate_grant] grant name '{name}' is declared more than once; give every grant a unique name"
            ),
            EnvironmentPolicyError::DuplicateExposureTarget { target } => write!(
                f,
                "[environment_policy.duplicate_exposure_target] environment target '{target}' is exposed by more than one grant; choose one grant for each target"
            ),
            EnvironmentPolicyError::ChildPolicyExceedsParent {
                parent,
                requested,
                offending_grant: _,
                detail,
            } => write!(
                f,
                "[environment_policy.child_exceeds_parent] child policy '{}' exceeds parent policy '{}': {detail}",
                requested.as_str(),
                parent.as_str()
            ),
            EnvironmentPolicyError::MissingSecret { name } => {
                write!(
                    f,
                    "[environment_policy.secret_unavailable] grant '{name}' is unavailable from the secret store; restore access, rotate the reference, or remove the grant"
                )
            }
        }
    }
}

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

impl EnvironmentPolicyError {
    /// Stable machine-readable code for CLI, ACP, and host integrations.
    pub fn code(&self) -> &'static str {
        match self {
            Self::EmptyName => "environment_policy.empty_grant_name",
            Self::EmptyEnvVar { .. } => "environment_policy.empty_source_variable",
            Self::LiteralSecretReference { .. } => "environment_policy.literal_secret_reference",
            Self::EmptySecretRef { .. } => "environment_policy.empty_secret_reference",
            Self::EmptyExposeVar { .. } => "environment_policy.empty_exposure_target",
            Self::EmptyForCommand { .. } => "environment_policy.empty_for_command",
            Self::ForWithoutExpose { .. } => "environment_policy.for_without_expose",
            Self::InvalidForCommand { .. } => "environment_policy.invalid_for_command",
            Self::InProcessWithoutExpose { .. } => "environment_policy.in_process_without_expose",
            Self::InProcessWithCommand { .. } => "environment_policy.in_process_with_command",
            Self::MissingEnv { .. } => "environment_policy.source_variable_missing",
            Self::PolicyForbidsGrants { .. } => "environment_policy.grants_forbidden",
            Self::DuplicateGrant { .. } => "environment_policy.duplicate_grant",
            Self::DuplicateExposureTarget { .. } => "environment_policy.duplicate_exposure_target",
            Self::ChildPolicyExceedsParent { .. } => "environment_policy.child_exceeds_parent",
            Self::MissingSecret { .. } => "environment_policy.secret_unavailable",
        }
    }

    /// Non-secret structured diagnostic for JSON-RPC and machine consumers.
    pub fn to_json(&self) -> serde_json::Value {
        let mut value = serde_json::json!({
            "code": self.code(),
            "message": self.to_string(),
        });
        let object = value
            .as_object_mut()
            .expect("environment policy diagnostic is an object");
        match self {
            Self::LiteralSecretReference { name }
            | Self::EmptyEnvVar { name }
            | Self::EmptySecretRef { name }
            | Self::EmptyExposeVar { name }
            | Self::EmptyForCommand { name }
            | Self::ForWithoutExpose { name }
            | Self::InProcessWithoutExpose { name }
            | Self::InProcessWithCommand { name }
            | Self::MissingSecret { name } => {
                object.insert("grant".to_string(), serde_json::json!(name));
            }
            Self::InvalidForCommand { name, command } => {
                object.insert("grant".to_string(), serde_json::json!(name));
                object.insert("forCommand".to_string(), serde_json::json!(command));
            }
            Self::MissingEnv { name, var } => {
                object.insert("grant".to_string(), serde_json::json!(name));
                object.insert("sourceVariable".to_string(), serde_json::json!(var));
            }
            Self::PolicyForbidsGrants { policy, attempted } => {
                object.insert("policy".to_string(), serde_json::json!(policy.as_str()));
                object.insert("attemptedGrants".to_string(), serde_json::json!(attempted));
            }
            Self::DuplicateGrant { name } => {
                object.insert("grant".to_string(), serde_json::json!(name));
            }
            Self::DuplicateExposureTarget { target } => {
                object.insert("target".to_string(), serde_json::json!(target));
            }
            Self::ChildPolicyExceedsParent {
                parent,
                requested,
                offending_grant,
                detail,
            } => {
                object.insert(
                    "parentPolicy".to_string(),
                    serde_json::json!(parent.as_str()),
                );
                object.insert(
                    "requestedPolicy".to_string(),
                    serde_json::json!(requested.as_str()),
                );
                object.insert("detail".to_string(), serde_json::json!(detail));
                if let Some(grant) = offending_grant {
                    object.insert("grant".to_string(), serde_json::json!(grant));
                }
            }
            Self::EmptyName => {}
        }
        value
    }
}

#[cfg(test)]
#[path = "session_environment_tests.rs"]
mod tests;