feat(vz): enable delivered secret-shim mediation

Author: Marco Napetti

crates/firma-run/src/backend/macos_vz.rs

@@ -335,9 +335,9 @@ impl SandboxBackend for VzBackend {
                     reason: SecretShimUnsupportedReason::HostCallable,
                 }
             }
-            VzStructuralMode::VzGuest => SecretShimSupport::Unsupported {
-                reason: SecretShimUnsupportedReason::HostCallable,
-            },
+            VzStructuralMode::VzGuest => {
+                isolated_guest_shim_support(ShimTarget::linux_musl(), None)
+            }
         }
     }
 

docs-site/public/llms.txt

@@ -63,3 +63,4 @@ OpenFirma docs highlights for LLM-based retrieval:
 - Composio Cedar context includes `composio_toolkit`, `composio_tool_slug`, `composio_user_id`, `composio_account`, `composio_session_id`, `composio_batch_index`, and `composio_batch_size`. Signed audit events identify each tool through its canonical action class and `composio://<toolkit>/<tool_slug>` resource without changing the shared protobuf contract or recording credentials, raw arguments, request selectors, or provider response bodies.
 - The secret gateway (`fsp_…` placeholder tokens) is a distinct mechanism from static credential injection: the Sidecar rehydrates outbound placeholders and masks inbound secret echoes via `firma-run`'s broker over `FIRMA_SECRET_GATEWAY_ADDR` (`unix://` or `tcp://` endpoint), and can also intercept configured HTTP vault responses (`[[sidecar.http_secret_providers]]`) to extract, placeholder-ize, and push newly seen secrets. All three paths are fail-closed: rehydration denies the whole request if any placeholder can't be resolved (never forwards a partially-substituted body), a `blocked_command` HTTP vault path is rejected before the connector is ever contacted (not dispatched then discarded), and a failed push to the broker aborts the response (`CREDENTIAL_INJECTION_FAILED`) rather than hand the agent an unresolvable placeholder. Invalid HTTP-provider matchers and HTTP providers configured without a gateway reject Sidecar startup.
 - `firma run` `secret_providers` in `firma.toml` automates the gateway for its per-run Sidecar: `[run.defaults]` / `[run.profiles.<id>] secret_providers` entries are either a bare string naming a built-in CLI integration (e.g. `"bws"`, `"op"`) or a full table `{ type = "cli", binary_name, provider_id, credential_env_vars, matchers = [{type="sensitive_command"|"safe_command"|"blocked_command", argv, matcher, stripped_options, append_options}] }` or `{ type = "http", provider_id, host, matchers = [{type="sensitive_command"|"safe_command"|"blocked_command", path, matcher}] }`. CLI entries activate an in-sandbox shim via the `firma-run` broker; HTTP entries are mirrored into the synthesized `[sidecar].http_secret_providers`. Merge: defaults + active profile, later wins on `binary_name` (CLI) / `provider_id` (HTTP); unknown bare name fails closed; presence is authorization.
+- The repository-owned `curl | sh` installer keeps `firma-secret-shim` out of `PATH`. Tarball installs use `libexec/openfirma/secret-shims/<linux-musl-target>/` relative to the installed `firma`; the macOS Homebrew branch checksum-fetches and preinstalls its version-qualified resource under `$(brew --prefix)/var/openfirma/secret-shims/<version>/<linux-musl-target>/` before invoking Brew, outside versioned kegs. Linux uses the shim from its primary release archive. A custom VZ guest bundle records the exact required shim digest in `manifest.txt`. A direct `brew install Firma-AI/openfirma/firma` remains CLI-only until the external tap packages that private resource. Explicit installs of published releases through `v0.1.6` are also CLI-only because those archives predate private shim packaging; a missing shim in a current or newer release aborts before changing the installation.

docs-site/src/content/docs/guides/secret-gateway.md

@@ -72,6 +72,32 @@ not supported — define them as a full `{ type = "http", ... }` table.
   under opaque `fsp_…` placeholders the gateway resolves later. An entry being
   present is itself the authorization to intercept — no separate policy check
   gates it.
+
+  CLI secret mediation is available on backends that declare shim support:
+  the Linux bwrap backend (host bind-mount) and the macOS VZ guest backend
+  (isolated guest with VSOCK broker bridge). WSL2 and sandbox-exec
+  compatibility mode are unsupported because the wrapped process can call the
+  host directly, so a shim would be redundant. Firecracker support is planned
+  but not yet implemented.
+
+  Install with the repository-owned `curl | sh` installer to receive the
+  target-qualified private shim used by these backends. On macOS, that
+  installer completes both its tarball and Homebrew branches by downloading
+  and checksum-verifying the matching Linux-musl shim archive. Running
+  `brew install Firma-AI/openfirma/firma` directly currently installs the CLI
+  only because the external tap does not yet package this private resource;
+  VZ CLI-provider mediation then fails closed during preflight. The shim is
+  intentionally not exposed on `PATH`.
+  A custom VZ guest bundle records the exact shim digest in `manifest.txt`;
+  install that matching shim rather than mixing artifacts from another build.
+  Published releases through `v0.1.6` predate this private artifact. When one
+  of those versions is explicitly selected with `--version`, the installer
+  reports that it is installing the historical CLI only; missing shims in
+  current or newer release archives abort before the installation is changed.
+  Tarball installs keep the shim under
+  `libexec/openfirma/secret-shims/<linux-musl-target>/` beside `firma`.
+  The Homebrew branch preinstalls it outside versioned kegs under
+  `$(brew --prefix)/var/openfirma/secret-shims/<version>/<linux-musl-target>/`.
 - **HTTP entry** — mirrored into the autostarted Sidecar's
   `[sidecar].http_secret_providers` so the Sidecar's MITM path can intercept
   matching vault responses. Fail-closed: an unknown vault path is `blocked`, a

docs-site/src/content/docs/quickstart.mdx

@@ -7,7 +7,7 @@ import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
 
 This quickstart takes you from nothing installed to a real agent running under enforcement: its outbound calls are checked against policy, allowed or denied, and written to the audit log.
 
-The default install path uses a single precompiled static binary. You do not need a build toolchain, or any API keys, unless you choose to build from source.
+The default install path uses precompiled static binaries. You do not need a build toolchain, or any API keys, unless you choose to build from source.
 
 ## Install
 
@@ -42,7 +42,7 @@ OpenFirma can be installed with a one-line script or built from source. The scri
 
 </Steps>
 
-The installer drops the binary in `~/.local/bin` by default and adds it to your shell's `PATH`.
+The tarball installer drops `firma` in `~/.local/bin` by default and adds that directory to your shell's `PATH`. It keeps backend support binaries in a private `libexec/openfirma` directory beside `firma`. The Homebrew path stores its private guest shim under `$(brew --prefix)/var/openfirma/secret-shims/<version>/<target>/` instead. These support binaries are not commands and must not be added to `PATH`.
 
 </TabItem>
 <TabItem label="From source">

examples/firma-run/macos-vz-basic-exec/README.md

@@ -90,5 +90,6 @@ generated by the artifact builder:
 vmlinuz
 initrd.img
 rootfs.img
+firma-secret-shim
 manifest.txt
 ```