GatewayClient

Module: gateway::client::GatewayClient

Contents

Functions

• push_secret - Push a secret newly extracted from an intercepted HTTP vault response.
• resolve_batch - Resolve a batch of placeholder tokens to their raw secret bytes via the

---

firma_secret_provider::gateway::client::GatewayClient::push_secret

Function

Push a secret newly extracted from an intercepted HTTP vault response.

placeholder must already be minted by the caller (via firma_secret_provider::mint_placeholder, from the same placeholder_template firma-run resolved and mirrored into the Sidecar’s config) — the Sidecar mints locally so it can substitute the placeholder synchronously into the response body during extraction, and the gateway stores it as-is rather than re-deriving it, so the stored key can never diverge from what the agent actually sees. The counterpart of [GatewayClient::resolve_batch] for the write direction: extraction happens in the Sidecar (via firma_secret_provider::CompiledMatcher), but firma-run’s broker remains the single owner of the secret dictionary, so the extracted value is pushed there rather than cached locally.

domain scopes the pushed secret to that request hosts, mirroring a CLI intercept’s domain_selector-derived scope; an empty set means it’s unscoped (resolves for any request host) — the common case for HTTP vaults, whose response carries a credential meant for later use against some other downstream host, not the vault itself.

Errors

Returns an error string if the gateway is unreachable, the response cannot be decoded, or the gateway rejects the push (e.g. malformed placeholder). Callers should treat any error as fail-closed: do not substitute the placeholder into the response the agent sees.

fn push_secret(self: &Self, placeholder: SecretPlaceholder, value: SecretString, domain: HashSet<Authority>) -> Result<SecretPlaceholder, GatewayClientError>

firma_secret_provider::gateway::client::GatewayClient::resolve_batch

Function

Resolve a batch of placeholder tokens to their raw secret bytes via the firma-run secret gateway.

All tokens are sent in a single request; the wire response is a positionally-aligned array of per-token results, but resolution here is all-or-nothing: the first unresolved placeholder fails the whole batch. domain is the target host of the outbound request; secrets stored for a different domain will not resolve.

The outer Result represents a connection or protocol failure that affects the entire batch. The inner Result represents whether every placeholder in the batch was known to firma-run for this domain; one unknown placeholder fails the whole batch, not just that placeholder.

Errors

The outer error is returned when the gateway is unreachable or the response cannot be decoded. The inner error is returned when any placeholder in the batch is unknown or scoped to a different domain, which fails the whole batch. Treat both error variants as fail-closed for the whole batch: do not substitute any literal token into the request body, and deny the outbound request instead.

fn resolve_batch(self: &Self, placeholders: &[SecretPlaceholder], domain: Authority) -> Result<Result<Vec<SecretString>, ResolveError>, GatewayClientError>