broker

Module: broker

Contents

Modules

• client - Client for the out-of-sandbox secret broker.
• server - Broker-side listener: accepts shim connections and dispatches requests.
• stream

Structs

• BinaryName - A validated executable basename from a shim request.
• BrokerOutput - Raw output and termination status from a broker-executed tool.
• BrokerRequest - Shim → broker request: describes one tool invocation, which the broker’s

Enums

• BinaryNameError - Validation failures for [BinaryName].
• BrokerExitStatus - A platform-neutral process termination status returned by the broker.
• BrokerOutputChunk - One stream-tagged chunk of raw process output.
• BrokerResponse - Broker → shim response.
• BrokerResponseChunk - One base64-encoded, stream-tagged output chunk in a broker response.
• BrokerResponseDecodeError - Invalid base64 in a broker execution response.
• DecodedBrokerResponse - A decoded broker response.

---

firma_secret_provider::broker::BinaryName

Struct

A validated executable basename from a shim request.

The broker resolves executable names outside the sandbox, so wire input must remain one path component on both Unix and Windows. In particular, absolute paths, parent traversal, and platform-specific separators are rejected before a request reaches the handler.

Generic Parameters:

• ‘a

Tuple Struct: ()

Methods:

• fn new<impl Into<Str<'a>>>(value: impl Trait) -> Result<Self, BinaryNameError> - Validate value as a portable executable basename.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BinaryName<'a>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Display
  • fn fmt(self: &Self, formatter: & mut std::fmt::Formatter) -> std::fmt::Result
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Deserialize
  • fn deserialize<D>(deserializer: D) -> Result<Self, <D as >::Error>
• PartialEq
  • fn eq(self: &Self, other: &BinaryName<'a>) -> bool
• Deref
  • fn deref(self: &Self) -> &<Self as >::Target

firma_secret_provider::broker::BinaryNameError

Enum

Validation failures for [BinaryName].

Variants:

• Empty - An executable basename cannot be empty.
• NotBasename(String) - The value is not exactly one portable path component.

Traits: Eq, Error

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BinaryNameError
• PartialEq
  • fn eq(self: &Self, other: &BinaryNameError) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

firma_secret_provider::broker::BrokerExitStatus

Enum

A platform-neutral process termination status returned by the broker.

Variants:

• Exited{ code: i32 } - The process exited normally with code.
• Signaled{ signal: i32 } - The process was terminated by a Unix signal.
• Unknown - The platform reported neither an exit code nor a Unix signal.

Traits: Copy, Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BrokerExitStatus
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• From
  • fn from(status: std::process::ExitStatus) -> Self
• PartialEq
  • fn eq(self: &Self, other: &BrokerExitStatus) -> bool
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>

firma_secret_provider::broker::BrokerOutput

Struct

Raw output and termination status from a broker-executed tool.

Fields:

• output: Vec<BrokerOutputChunk> - Stream-tagged bytes in observed capture order.
• status: BrokerExitStatus - How the real tool terminated.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BrokerOutput
• PartialEq
  • fn eq(self: &Self, other: &BrokerOutput) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_secret_provider::broker::BrokerOutputChunk

Enum

One stream-tagged chunk of raw process output.

Variants:

• Stdout(Vec<u8>) - Bytes observed on stdout.
• Stderr(Vec<u8>) - Bytes observed on stderr.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BrokerOutputChunk
• PartialEq
  • fn eq(self: &Self, other: &BrokerOutputChunk) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_secret_provider::broker::BrokerRequest

Struct

Shim → broker request: describes one tool invocation, which the broker’s handler may refuse (config matching and authorization happen downstream in the handler, not in the shim).

Generic Parameters:

• ‘a

Fields:

• bin: BinaryName<'a> - Executable basename of the wrapped tool (e.g. "bws").
• args: Vec<firma_http::Str<'a>> - Arguments (everything after the binary name).

Traits: Eq

Trait Implementations:

• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Clone
  • fn clone(self: &Self) -> BrokerRequest<'a>
• PartialEq
  • fn eq(self: &Self, other: &BrokerRequest<'a>) -> bool

firma_secret_provider::broker::BrokerResponse

Enum

Broker → shim response.

Generic Parameters:

• ‘a

Variants:

• Executed{ output: Vec<BrokerResponseChunk<'a>>, status: BrokerExitStatus } - The real tool ran. Its complete observable process result follows.
• Rejected{ error: firma_http::Str<'a> } - The broker refused or failed to launch the real tool.

Methods:

• fn executed<impl IntoIterator<Item = BrokerOutputChunk>>(output: impl Trait, status: BrokerExitStatus) -> Self - Build an execution response from stream-tagged output chunks and status.
• fn rejected<'a, impl Into<Str<'a>>>(reason: impl Trait) -> BrokerResponse<'a> - Build a rejection response.
• fn decode(self: Self) -> Result<DecodedBrokerResponse, BrokerResponseDecodeError> - Decode an execution response’s output chunks.

Trait Implementations:

• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Clone
  • fn clone(self: &Self) -> BrokerResponse<'a>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_secret_provider::broker::BrokerResponseChunk

Enum

One base64-encoded, stream-tagged output chunk in a broker response.

Generic Parameters:

• ‘a

Variants:

• Stdout{ data: firma_http::Str<'a> } - Bytes observed on stdout.
• Stderr{ data: firma_http::Str<'a> } - Bytes observed on stderr.

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> BrokerResponseChunk<'a>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>

firma_secret_provider::broker::BrokerResponseDecodeError

Enum

Invalid base64 in a broker execution response.

Variants:

• Stdout{ index: usize, source: base64::DecodeError } - A stdout chunk is not valid base64.
• Stderr{ index: usize, source: base64::DecodeError } - A stderr chunk is not valid base64.

Trait Implementations:

• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
• Error
  • fn source(self: &Self) -> ::core::option::Option<&dyn ::thiserror::__private18::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_secret_provider::broker::DecodedBrokerResponse

Enum

A decoded broker response.

Variants:

• Executed(BrokerOutput) - The real tool ran and produced this observable result.
• Rejected(String) - The broker refused or failed to launch the real tool.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> DecodedBrokerResponse
• PartialEq
  • fn eq(self: &Self, other: &DecodedBrokerResponse) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

Module: client

Client for the out-of-sandbox secret broker.

The shim binary runs inside the sandbox and uses [BrokerClient] to ask the broker (running out of the sandbox, inside firma-run) to run the real CLI tool and return its [BrokerOutput]: stream-tagged chunks in observed capture order plus termination status. Whether the tool is authorized to run is decided downstream by the broker’s handler (config matching and authorization), which reports a refused or failed launch back as an error. [BrokerClient] opens a fresh connection per call rather than pooling, since broker calls are infrequent relative to tool launches, and applies the timeouts and buffer limits from [BrokerClientConfig] to every operation.

All operations are fail-closed: any connect, timeout, protocol, or rejected error means the wrapped tool produced no usable output, and the caller must treat the invocation as failed rather than substituting a partial or synthetic result.

Module: server

Broker-side listener: accepts shim connections and dispatches requests.

The broker is a trust boundary: its handler applies config matching and authorization to decide what can run, executes the real CLI out of the sandbox, and returns secret material, so the listener restricts who can connect. On Unix the socket file is created owner-only (0600), and the connecting shim’s credentials are validated to belong to the current user before the request is read. A connection that fails these checks receives an error response and is closed without running the tool.

A same-user local process is trusted: it already has the user’s secrets. The boundary enforced here is cross-user access.

Concurrency: [BrokerListener::accept_one] services exactly one connection, so an accept loop that awaits it serially runs tools one at a time — new connections queue in the kernel backlog and their shims can time out while a slow tool holds the broker. Callers that want tools to run concurrently should spawn a task per accept_one (each call takes &self, so concurrent accepts are safe). Note that [config::BrokerListenerConfig::operation_timeout] cancels the handler mid-run when it fires: a handler that spawns a child process must ensure the child is killed on cancellation, or the tool keeps running out of the sandbox after the shim has already failed closed.

Module: stream