feat(run)!: require canonical capability seeds

Amp-Thread-ID: https://ampcode.com/threads/T-01a042e7-9125-736f-9bdc-ce404c78d707

Author: LukeMathWalker

crates/firma-authority/README.md

@@ -75,8 +75,10 @@ cargo run -p firma-authority -- --config firma.toml issue   --agent-id agt_01j00
 ```
 
 The output file contains the signed token and matching claims. Pass it to
-`firma run --capability-file capability-demo-agent.toml`; `firma run` and the
-Sidecar verify it with the configured Authority public key before use.
+`firma run --capability-file capability-demo-agent.toml`; Run parses this
+canonical seed TOML and exports only its raw token to the wrapped process. A
+locally autostarted Sidecar also loads the file and verifies its token and
+matching claims with the configured Authority public key.
 
 ## Configuration
 

crates/firma-core/src/capability_seed.rs

@@ -14,6 +14,7 @@ use crate::CapabilityClaims;
 /// [`CapabilityClaims`]; the `raw_token` is authoritative and re-verified at
 /// load time.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
 pub struct CapabilitySeed {
     /// Raw PASETO v4.public token string.
     pub raw_token: String,
@@ -109,4 +110,16 @@ context_hash = "cafebabe"
                 .unwrap()
         );
     }
+
+    #[test]
+    fn rejects_unknown_fields() {
+        let claims = sample_claims();
+        let seed = CapabilitySeed::from_claims(&claims, "v4.public.tok".to_string());
+        let body = format!("{}unknown = \"value\"\n", toml::to_string(&seed).unwrap());
+
+        let error = toml::from_str::<CapabilitySeed>(&body)
+            .expect_err("unknown fields must fail the canonical seed boundary");
+
+        assert!(error.message().contains("unknown field"));
+    }
 }

crates/firma-run/src/capability/mod.rs

@@ -9,16 +9,18 @@ use crate::error::RunError;
 
 /// Read the operator-supplied capability token for a `firma run` session.
 ///
-/// Only [`CapabilitySource::File`] carries a bring-your-own token; the token is
-/// injected into the agent process environment once at launch (see
-/// `build_execution_env`). Rotation is delegated to the agent via the
-/// `FIRMA_CAPABILITY_FILE` env var, so this is a one-shot read with no
-/// background refresh — the firma-minted per-session path uses
-/// [`refresh::CapabilityRefresher`] instead.
+/// Only [`CapabilitySource::File`] carries an operator-provided seed. Run parses
+/// the canonical [`firma_core::CapabilitySeed`] TOML and injects only its
+/// `raw_token` into the agent process environment (see `build_execution_env`).
+/// This is a one-shot Run read with no Run-managed background refresh. A local
+/// Sidecar independently reads and watches the same file; a pre-managed
+/// external Sidecar owns its seed configuration. The Firma-minted per-session
+/// path uses [`refresh::CapabilityRefresher`] instead.
 ///
 /// # Errors
 ///
-/// Returns [`RunError::Capability`] when the file is unreadable or empty.
+/// Returns [`RunError::Capability`] when the file is unreadable, is not a
+/// canonical capability seed, or contains an empty `raw_token`.
 pub fn read_capability_token(source: &CapabilitySource) -> Result<Option<String>, RunError> {
     match source {
         CapabilitySource::Disabled => Ok(None),
@@ -27,16 +29,21 @@ pub fn read_capability_token(source: &CapabilitySource) -> Result<Option<String>
 }
 
 fn read_token(path: &Path) -> Result<String, RunError> {
-    let value = std::fs::read_to_string(path)
+    let body = std::fs::read_to_string(path)
         .map_err(|error| RunError::Capability(format!("{}: {error}", path.display())))?;
+    let seed: firma_core::CapabilitySeed = toml::from_str(&body).map_err(|_| {
+        RunError::Capability(format!(
+            "capability seed '{}' is not canonical CapabilitySeed TOML",
+            path.display()
+        ))
+    })?;
 
-    let token = value.trim().to_string();
-    if token.is_empty() {
+    if seed.raw_token.trim().is_empty() {
         return Err(RunError::Capability(format!(
-            "capability file {} is empty",
+            "capability seed '{}' has an empty raw_token",
             path.display()
         )));
     }
 
-    Ok(token)
+    Ok(seed.raw_token)
 }

crates/firma-run/src/routing.rs

@@ -284,7 +284,7 @@ pub struct AutostartFlags {
     /// Sidecar credential config injected into `[sidecar.authority.credentials]`
     /// during sidecar config synthesis.
     pub authority_credentials: Option<SidecarCredentialsConfig>,
-    /// Path of the per-session capability seed minted by `firma run`.
+    /// Explicit or Firma-minted capability seed path for local Sidecar setup.
     pub capability_seed_path: Option<PathBuf>,
     /// When `true`, the autostarted sidecar is started in HTTP proxy
     /// interceptor mode rather than Unix socket mode.

crates/firma-run/src/runtime/mod.rs

@@ -40,8 +40,8 @@ pub struct RunInput {
     pub backend: Option<crate::backend::BackendKind>,
     /// CLI value of `--sidecar` (`local` | `<tcp://...|unix:///...>` | unset).
     pub sidecar_cli: crate::sidecar::SidecarCli,
-    /// Optional operator-supplied capability token file, injected into the
-    /// agent environment at launch (bring-your-own token).
+    /// Optional canonical signed capability seed TOML. Run exports only its raw
+    /// token and the original file path to the agent environment at launch.
     pub capability_file: Option<PathBuf>,
     /// Override sandbox identity mode.
     pub identity_mode: Option<crate::config::SandboxIdentityMode>,
@@ -837,6 +837,21 @@ mod tests {
     use super::{RunIdentity, build_execution_env};
     use crate::backend::SandboxHandle;
 
+    fn canonical_seed_toml(raw_token: &str) -> String {
+        format!(
+            r#"raw_token = "{raw_token}"
+token_id = "ctok_01j0000000e008000000000001"
+agent_id = "agt_01j0000000e008000000000001"
+session_id = "sess_runtime"
+action_set = ["communication.external.send"]
+resource_scope = "*"
+issued_at = "2026-04-29T15:00:00Z"
+expiry = "2026-04-29T16:00:00Z"
+context_hash = "runtime-seed-canary"
+"#
+        )
+    }
+
     /// Quotes a path the way the platform's VS Code shim does.
     fn quote_shim_path(path: &std::path::Path) -> String {
         let value = path.display().to_string();
@@ -941,64 +956,81 @@ mod tests {
     }
 
     #[test]
-    fn capability_file_is_exported_when_file_source_is_used() {
+    fn capability_file_exports_exact_token_and_path_for_local_and_external_sidecars() {
         let tempdir = tempfile::tempdir().unwrap_or_else(|e| panic!("{e}"));
-        let token_path = tempdir.path().join("cap.token");
-        fs::write(&token_path, "token").unwrap_or_else(|e| panic!("{e}"));
+        let seed_path = tempdir.path().join("capability.toml");
+        let raw_token = "v4.public.exact-runtime-token";
+        let seed_document = canonical_seed_toml(raw_token);
+        fs::write(&seed_path, &seed_document).unwrap_or_else(|e| panic!("{e}"));
+        let endpoint = SidecarEndpoint::Tcp {
+            addr: "127.0.0.1:8080".parse().unwrap_or_else(|e| panic!("{e}")),
+        };
 
-        let profile = ResolvedProfile {
-            id: "generic".to_string(),
-            backend: crate::backend::BackendKind::Bwrap,
-            sidecar_endpoint: SidecarEndpoint::Tcp {
-                addr: "127.0.0.1:8080".parse().unwrap_or_else(|e| panic!("{e}")),
-            },
-            sidecar_selection: crate::sidecar::SidecarSelection::Local,
-            env_passthrough: BTreeSet::default(),
-            env_set: BTreeMap::default(),
-            mounts: Vec::new(),
-            seccomp_policy: None,
-            network: NetworkPolicy {
-                enforce_network_namespace: false,
-                fail_closed: true,
-            },
-            identity_mode: SandboxIdentityMode::SandboxUser,
-            capability: CapabilityLeaseConfig {
-                source: CapabilitySource::File {
-                    path: token_path.clone(),
+        for sidecar_selection in [
+            crate::sidecar::SidecarSelection::Local,
+            crate::sidecar::SidecarSelection::Remote(endpoint.clone()),
+        ] {
+            let profile = ResolvedProfile {
+                id: "generic".to_string(),
+                backend: crate::backend::BackendKind::Bwrap,
+                sidecar_endpoint: endpoint.clone(),
+                sidecar_selection,
+                env_passthrough: BTreeSet::default(),
+                env_set: BTreeMap::default(),
+                mounts: Vec::new(),
+                seccomp_policy: None,
+                network: NetworkPolicy {
+                    enforce_network_namespace: false,
+                    fail_closed: true,
                 },
-                public_key_path: None,
-                refresh_ratio: 0.60,
-                grace: Duration::from_secs(30),
-                requested_actions: CapabilityLeaseConfig::default_requested_actions(),
-            },
-            sidecar_local_exec: None,
-            secret_gateway_addr: None,
-            secret_providers: BTreeMap::new(),
-            executable_policies: BTreeMap::new(),
-            use_http_proxy_sidecar: false,
-            allow_non_structural: false,
-            ca_trust_mode: crate::config::CaTrustMode::Sole,
-        };
+                identity_mode: SandboxIdentityMode::SandboxUser,
+                capability: CapabilityLeaseConfig {
+                    source: CapabilitySource::File {
+                        path: seed_path.clone(),
+                    },
+                    public_key_path: None,
+                    refresh_ratio: 0.60,
+                    grace: Duration::from_secs(30),
+                    requested_actions: CapabilityLeaseConfig::default_requested_actions(),
+                },
+                sidecar_local_exec: None,
+                secret_gateway_addr: None,
+                secret_providers: BTreeMap::new(),
+                executable_policies: BTreeMap::new(),
+                use_http_proxy_sidecar: false,
+                allow_non_structural: false,
+                ca_trust_mode: crate::config::CaTrustMode::Sole,
+            };
 
-        let identity = RunIdentity::new(crate::identity::test_agent_id(), "generic");
-        let capability_token = crate::capability::read_capability_token(&profile.capability.source)
-            .unwrap_or_else(|e| panic!("{e}"));
+            let identity = RunIdentity::new(crate::identity::test_agent_id(), "generic");
+            let capability_token =
+                crate::capability::read_capability_token(&profile.capability.source)
+                    .unwrap_or_else(|e| panic!("{e}"));
 
-        let env = build_execution_env(
-            &profile,
-            &identity,
-            capability_token.as_deref(),
-            &profile.sidecar_endpoint,
-            &BTreeMap::default(),
-        );
-        assert_eq!(
-            env.get("FIRMA_CAPABILITY_FILE"),
-            Some(&token_path.display().to_string())
-        );
-        assert_eq!(
-            env.get("FIRMA_CAPABILITY_TOKEN"),
-            Some(&"token".to_string())
-        );
+            let env = build_execution_env(
+                &profile,
+                &identity,
+                capability_token.as_deref(),
+                &profile.sidecar_endpoint,
+                &BTreeMap::default(),
+            );
+            assert_eq!(
+                env.get("FIRMA_CAPABILITY_FILE"),
+                Some(&seed_path.display().to_string())
+            );
+            assert_eq!(
+                env.get("FIRMA_CAPABILITY_TOKEN").map(String::as_str),
+                Some(raw_token)
+            );
+            assert_ne!(
+                env.get("FIRMA_CAPABILITY_TOKEN").map(String::as_str),
+                Some(seed_document.as_str())
+            );
+            assert!(
+                !env.get("FIRMA_CAPABILITY_TOKEN")
+                    .is_some_and(|value| value.contains("runtime-seed-canary"))
+            );
+        }
     }
 
     #[test]

crates/firma-run/src/sidecar/config.rs

@@ -327,9 +327,9 @@ pub struct SynthesizeRequest<'a> {
     /// Sidecar credentials to inject into `[sidecar.authority.credentials]`.
     /// `None` leaves any existing template value untouched.
     pub authority_credentials: Option<&'a SidecarCredentialsConfig>,
-    /// Path of the per-session capability seed minted by `firma run`, appended
-    /// to `[sidecar.capability_seed].paths`. `None` when no seed was minted
-    /// (e.g. `--capability-file` was passed).
+    /// Capability seed path appended to `[sidecar.capability_seed].paths`.
+    /// This is either an explicit file source or a per-session seed minted by
+    /// `firma run`; `None` means no seed is available for local Sidecar setup.
     pub capability_seed_path: Option<&'a Path>,
     /// Audit log path used as the default `file` sink when the template does
     /// not configure an audit sink. Set to the shared state/runtime dir's