fix(policy): address approval loop review feedback

Signed-off-by: Alexander Watson <zredlined@gmail.com>

Author: zredlined

architecture/security-policy.md

@@ -91,6 +91,9 @@ because it changes the effective access model for every sandbox on the gateway.
 The policy advisor pipeline turns observed denials into draft policy
 recommendations. There are two proposers (sandbox-side mechanistic mapper,
 agent-authored via `policy.local`); the gateway is the single referee.
+When enabled, L7 `policy_denied` responses include both structured
+`next_steps` and a short `agent_guidance` string so generic agents can continue
+through the proposal loop instead of treating the denial as terminal.
 
 1. **Submit.** Both proposers POST through the same `SubmitPolicyAnalysis`
    path. Each chunk is persisted with its `analysis_mode` for audit provenance.
@@ -130,15 +133,17 @@ than one reach + N method findings.
 
 | Category | The prover detects… |
 |---|---|
-| `link_local_reach` | The proposal grants reach to a host in `169.254.0.0/16` or `fe80::/10`. Unconditional — cloud-metadata endpoints serve credentials regardless of sandbox state. |
+| `link_local_reach` | The proposal grants reach to a host in `169.254.0.0/16`, `fe80::/10`, or a known metadata hostname such as `metadata.google.internal`. Unconditional — cloud-metadata endpoints serve credentials regardless of sandbox state. |
 | `l7_bypass_credentialed` | The proposal lets a binary using a non-HTTP wire protocol (`git-remote-https`, `ssh`, `nc`) reach a host where a sandbox credential is in scope. The L7 proxy cannot inspect the wire protocol; the reviewer decides whether to trust the binary with the credential. |
 | `credential_reach_expansion` | A binary gained credentialed reach to a (host, port) it could not reach before. New authenticated reach is a stated intent change; the reviewer confirms the binary should authenticate to the host at all. |
 | `capability_expansion` | On a (binary, host, port) that already had credentialed reach, the policy adds a new HTTP method. The reviewer sees exactly which method was added (e.g., PUT) and decides if it's part of the agent's task. |
 
 "Credential in scope" is sandbox-coarse, not binary-fine: a credential is
 considered in scope if the sandbox has a provider attached whose
-`target_hosts` include the proposed endpoint's host. v1 does not model
-credential scopes (read-only vs write); presence is enough.
+`target_hosts` include the proposed endpoint's host, including runtime-like
+first-label wildcard coverage such as `*.github.com` covering
+`api.github.com`. v1 does not model credential scopes (read-only vs write);
+presence is enough.
 
 Proposals intentionally omit `allowed_ips`. If a proposed rule targets a host
 that resolves to a private IP, the proxy's runtime SSRF classification blocks

crates/openshell-cli/src/run.rs

@@ -5557,14 +5557,16 @@ fn parse_cli_setting_value(key: &str, raw_value: &str) -> Result<SettingValue> {
             // proposal_approval_mode autom` errors immediately instead of
             // round-tripping through the server. The server enforces the
             // same check independently for non-CLI callers.
-            setting.validate_string_value(raw_value).map_err(|allowed| {
-                miette::miette!(
-                    "invalid value '{}' for key '{}'; expected one of: {}",
-                    raw_value,
-                    key,
-                    allowed.join(", ")
-                )
-            })?;
+            setting
+                .validate_string_value(raw_value)
+                .map_err(|allowed| {
+                    miette::miette!(
+                        "invalid value '{}' for key '{}'; expected one of: {}",
+                        raw_value,
+                        key,
+                        allowed.join(", ")
+                    )
+                })?;
             setting_value::Value::StringValue(raw_value.to_string())
         }
         SettingValueKind::Int => {

crates/openshell-core/src/net.rs

@@ -12,6 +12,16 @@
 
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
 
+/// Check if a hostname is a known cloud metadata hostname that resolves to an
+/// always-blocked metadata service.
+///
+/// This is intentionally a static name check. Do not perform DNS resolution in
+/// policy validation or proposal generation paths.
+pub fn is_known_metadata_hostname(host: &str) -> bool {
+    let normalized = host.trim().trim_end_matches('.').to_ascii_lowercase();
+    matches!(normalized.as_str(), "metadata.google.internal")
+}
+
 /// Check if an IP address is link-local.
 ///
 /// Covers IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`, and IPv4-mapped IPv6
@@ -213,6 +223,21 @@ fn is_internal_v4(v4: Ipv4Addr) -> bool {
 mod tests {
     use super::*;
 
+    // -- is_known_metadata_hostname --
+
+    #[test]
+    fn test_known_metadata_hostname_accepts_gcp_variants() {
+        assert!(is_known_metadata_hostname("metadata.google.internal"));
+        assert!(is_known_metadata_hostname("METADATA.GOOGLE.INTERNAL"));
+        assert!(is_known_metadata_hostname("metadata.google.internal."));
+    }
+
+    #[test]
+    fn test_known_metadata_hostname_rejects_public_hosts() {
+        assert!(!is_known_metadata_hostname("api.github.com"));
+        assert!(!is_known_metadata_hostname(""));
+    }
+
     // -- is_link_local_ip --
 
     #[test]

crates/openshell-core/src/settings.rs

@@ -100,10 +100,11 @@ pub const AGENT_POLICY_PROPOSALS_ENABLED_KEY: &str = "agent_policy_proposals_ena
 /// global is set.
 pub const PROPOSAL_APPROVAL_MODE_KEY: &str = "proposal_approval_mode";
 
-/// Allowed values for [`PROPOSAL_APPROVAL_MODE_KEY`]. Any other string is
-/// rejected at configure time (so operators get immediate feedback on typos
-/// like `"autom"`) while the runtime resolver still fail-closes on unknown
-/// persisted values for defense in depth.
+/// Allowed values for [`PROPOSAL_APPROVAL_MODE_KEY`].
+///
+/// Any other string is rejected at configure time (so operators get immediate
+/// feedback on typos like `"autom"`) while the runtime resolver still
+/// fail-closes on unknown persisted values for defense in depth.
 pub const PROPOSAL_APPROVAL_MODE_VALUES: &[&str] = &["manual", "auto"];
 
 pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
@@ -242,7 +243,15 @@ mod tests {
     fn proposal_approval_mode_rejects_typos_and_future_modes() {
         let setting = setting_for_key(PROPOSAL_APPROVAL_MODE_KEY)
             .expect("proposal_approval_mode should be registered");
-        for bad in ["autom", "AUTO", "Manual", "", " auto", "auto_on_low_risk", "yes"] {
+        for bad in [
+            "autom",
+            "AUTO",
+            "Manual",
+            "",
+            " auto",
+            "auto_on_low_risk",
+            "yes",
+        ] {
             let err = setting
                 .validate_string_value(bad)
                 .expect_err(&format!("expected '{bad}' to be rejected"));

crates/openshell-prover/src/credentials.rs

@@ -135,27 +135,115 @@ pub struct CredentialSet {
 }
 
 impl CredentialSet {
-    /// Credentials that target a given host. Comparison is case-insensitive
-    /// so a policy author writing `API.github.com` matches credentials
-    /// registered for `api.github.com`.
+    /// Credentials that target a given host. Matching mirrors runtime host
+    /// policy semantics for exact names and first-label wildcards, so a
+    /// proposal for `*.github.com` is treated as credentialed when the
+    /// attached credential targets `api.github.com`.
     pub fn credentials_for_host(&self, host: &str) -> Vec<&Credential> {
-        let needle = host.to_ascii_lowercase();
         self.credentials
             .iter()
             .filter(|c| {
                 c.target_hosts
                     .iter()
-                    .any(|h| h.eq_ignore_ascii_case(&needle))
+                    .any(|target| host_patterns_overlap(host, target))
             })
             .collect()
     }
 
-    /// API capability registry for a given host. Case-insensitive match.
+    /// API capability registry for a given host. Exact matches win, then
+    /// wildcard host overlap is used so credentialed wildcard proposals can be
+    /// evaluated against concrete API capability registries.
     pub fn api_for_host(&self, host: &str) -> Option<&ApiCapability> {
+        let needle = normalize_host(host);
         self.api_registries
             .values()
-            .find(|api| api.host.eq_ignore_ascii_case(host))
+            .find(|api| normalize_host(&api.host) == needle)
+            .or_else(|| {
+                self.api_registries
+                    .values()
+                    .find(|api| host_patterns_overlap(host, &api.host))
+            })
+    }
+}
+
+fn normalize_host(host: &str) -> String {
+    host.trim().trim_end_matches('.').to_ascii_lowercase()
+}
+
+fn host_patterns_overlap(left: &str, right: &str) -> bool {
+    let left = normalize_host(left);
+    let right = normalize_host(right);
+    if left.is_empty() || right.is_empty() {
+        return false;
+    }
+    left == right || host_pattern_covers(&left, &right) || host_pattern_covers(&right, &left)
+}
+
+fn host_pattern_covers(pattern: &str, host: &str) -> bool {
+    let pattern_labels: Vec<&str> = pattern.split('.').collect();
+    let host_labels: Vec<&str> = host.split('.').collect();
+    let Some(first_pattern_label) = pattern_labels.first().copied() else {
+        return false;
+    };
+
+    if first_pattern_label == "**" {
+        let suffix = &pattern_labels[1..];
+        let host_suffix = host_labels
+            .len()
+            .checked_sub(suffix.len())
+            .map(|start| &host_labels[start..]);
+        return !suffix.is_empty()
+            && host_labels.len() > suffix.len()
+            && matches!(host_suffix, Some(host_suffix) if host_suffix == suffix);
+    }
+
+    if !first_pattern_label.contains('*') {
+        return false;
     }
+
+    // Runtime host wildcards only apply in the first DNS label. Wildcards in
+    // later labels are not treated as policy globs here.
+    pattern_labels.len() == host_labels.len()
+        && pattern_labels[1..] == host_labels[1..]
+        && wildcard_label_matches(first_pattern_label, host_labels[0])
+}
+
+fn wildcard_label_matches(pattern: &str, label: &str) -> bool {
+    if pattern == "*" {
+        return !label.is_empty();
+    }
+    if label.is_empty() || !pattern.contains('*') {
+        return false;
+    }
+
+    let parts: Vec<&str> = pattern.split('*').collect();
+    let mut remaining = label;
+
+    if let Some(prefix) = parts.first().copied().filter(|part| !part.is_empty()) {
+        let Some(stripped) = remaining.strip_prefix(prefix) else {
+            return false;
+        };
+        remaining = stripped;
+    }
+
+    if parts.len() > 2 {
+        for part in parts[1..parts.len() - 1]
+            .iter()
+            .copied()
+            .filter(|part| !part.is_empty())
+        {
+            let Some(offset) = remaining.find(part) else {
+                return false;
+            };
+            remaining = &remaining[offset + part.len()..];
+        }
+    }
+
+    parts
+        .last()
+        .copied()
+        .filter(|suffix| !suffix.is_empty())
+        .is_none_or(|suffix| remaining.ends_with(suffix))
 }
 
 // ---------------------------------------------------------------------------
@@ -276,3 +364,97 @@ pub fn load_credential_set_from_dir(
         api_registries,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn github_credential() -> Credential {
+        Credential {
+            name: "github-pat".to_string(),
+            cred_type: "github-pat".to_string(),
+            scopes: vec!["repo".to_string()],
+            injected_via: "GITHUB_TOKEN".to_string(),
+            target_hosts: vec!["api.github.com".to_string()],
+        }
+    }
+
+    fn github_api() -> ApiCapability {
+        ApiCapability {
+            api: "github".to_string(),
+            host: "api.github.com".to_string(),
+            port: 443,
+            credential_type: "github-pat".to_string(),
+            scope_capabilities: HashMap::new(),
+            action_risk: HashMap::new(),
+        }
+    }
+
+    #[test]
+    fn host_patterns_overlap_matches_exact_case_and_trailing_dot() {
+        assert!(host_patterns_overlap("API.GITHUB.COM.", "api.github.com"));
+        assert!(!host_patterns_overlap(
+            "api.github.com",
+            "uploads.github.com"
+        ));
+    }
+
+    #[test]
+    fn host_patterns_overlap_matches_first_label_wildcard_only() {
+        assert!(host_patterns_overlap("*.github.com", "api.github.com"));
+        assert!(!host_patterns_overlap("*.github.com", "github.com"));
+        assert!(!host_patterns_overlap(
+            "*.github.com",
+            "deep.api.github.com"
+        ));
+    }
+
+    #[test]
+    fn host_patterns_overlap_matches_intra_label_first_label_wildcard() {
+        assert!(host_patterns_overlap(
+            "api-*.github.com",
+            "api-v3.github.com"
+        ));
+        assert!(!host_patterns_overlap(
+            "api-*.github.com",
+            "uploads.github.com"
+        ));
+        assert!(!host_patterns_overlap(
+            "api.*.github.com",
+            "api.v3.github.com"
+        ));
+    }
+
+    #[test]
+    fn host_patterns_overlap_matches_recursive_first_label_wildcard() {
+        assert!(host_patterns_overlap("**.github.com", "api.github.com"));
+        assert!(host_patterns_overlap(
+            "**.github.com",
+            "deep.api.github.com"
+        ));
+        assert!(!host_patterns_overlap("**.github.com", "github.com"));
+    }
+
+    #[test]
+    fn wildcard_policy_host_finds_credentialed_concrete_target() {
+        let set = CredentialSet {
+            credentials: vec![github_credential()],
+            api_registries: HashMap::new(),
+        };
+
+        let creds = set.credentials_for_host("*.github.com");
+        assert_eq!(creds.len(), 1);
+        assert_eq!(creds[0].name, "github-pat");
+    }
+
+    #[test]
+    fn wildcard_policy_host_finds_concrete_api_registry() {
+        let set = CredentialSet {
+            credentials: Vec::new(),
+            api_registries: HashMap::from([("github".to_string(), github_api())]),
+        };
+
+        let api = set.api_for_host("*.github.com").expect("github API");
+        assert_eq!(api.host, "api.github.com");
+    }
+}