decision

Module: decision

Contents

Structs

• DeferDuration - Backoff duration for an AARM R4 DEFER decision.
• SecretJsonSelector - A JSONPath selector whose evaluation root is explicit.
• StepUpSpec - Human-readable challenge description for an AARM R4 STEP_UP decision.

Enums

• AbortReason - Typed reason code explaining why an already-authorized request was aborted.
• Decision - Outcome of policy evaluation.
• DenyReason - Typed reason code explaining why a request was denied.
• ModificationError - Errors that can arise when parsing or applying a [ModificationSpec].
• ModificationSpec - Structured transformation applied to a request under the AARM R4 MODIFY
• SecretJsonSelectorScope - Evaluation root for a [SecretJsonSelector].
• SecretMatcher - How to extract (name, value) pairs from a vault CLI’s stdout or an
• SecretNameSource - How a JSON record’s secret name is determined.

---

firma_core::decision::AbortReason

Enum

Typed reason code explaining why an already-authorized request was aborted.

Variants:

• ConnectorTimeout - Outbound connector exceeded its configured timeout.
• ConnectorFailure - Outbound connector failed before producing a target response.
• ConnectorInvalidRequest - Outbound connector rejected the authorized envelope shape.
• CredentialInjectionFailed - Sidecar failed to inject credentials after enforcement allowed the call.
• CredentialInjectionBlocked - Sidecar blocked operation for security reasons after enforcement allowed the call.
• BatchAtomicity - One logical action blocked an otherwise atomic multi-action request.

Methods:

• fn code(self: Self) -> &'static str - Canonical reason code string used in audit events and agent responses.

Traits: Error, Eq, Copy

Trait Implementations:

• PartialEq
  • fn eq(self: &Self, other: &AbortReason) -> bool
• Clone
  • fn clone(self: &Self) -> AbortReason
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

firma_core::decision::Decision

Enum

Outcome of policy evaluation.

Every enforcement decision in Firma maps to one of these three variants.

Variants:

• Allow - Request passes all checks. Proceed with execution.
• Deny{ reason: DenyReason } - Request denied. Return error to agent with reason code.
• Abort{ reason: String } - Critical failure. Kill the session/execution immediately.

Traits: Eq

Trait Implementations:

• PartialEq
  • fn eq(self: &Self, other: &Decision) -> bool
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• Clone
  • fn clone(self: &Self) -> Decision

firma_core::decision::DeferDuration

Struct

Backoff duration for an AARM R4 DEFER decision.

Validates at construction that the duration is strictly positive, so any value that survives into a PolicyVerdict::Defer is guaranteed to carry a non-zero retry window.

Tuple Struct: ()

Methods:

• fn new(duration: Duration) -> Result<Self, ModificationError> - Construct a [DeferDuration] from a [Duration].
• fn duration(self: &Self) -> Duration - Return the inner [Duration].

Traits: Eq, Copy

Trait Implementations:

• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• PartialEq
  • fn eq(self: &Self, other: &DeferDuration) -> bool
• Clone
  • fn clone(self: &Self) -> DeferDuration

firma_core::decision::DenyReason

Enum

Typed reason code explaining why a request was denied.

Backlog variant (add back when the corresponding mechanism exists):

• RiskThreshold — when anomaly detection is designed

Variants:

• TokenInvalid - Signature check failed or unrecognized token format.
• TokenExpired - Token TTL has elapsed.
• TokenRevoked - Token has been explicitly revoked.
• PolicyDenied - Cedar policy evaluation returned deny.
• ScopeViolation - Action or resource outside the token’s granted scope.
• ToolNotInScope - Specific tool not in the token’s allowed set.
• MalformedRequest - Execution envelope failed validation.
• AuthorityUnavailable - Cannot reach Authority for token validation.
• PolicyBundleStale - Policy bundle TTL exceeded, no fresh bundle available.
• PolicyBundleNotReady - Initial policy bundle has not been applied yet.
• RevocationCacheNotReady - Initial revocation state has not been applied yet.
• FailClosed - Fail-closed safety boundary triggered due to missing/invalid enforcement prerequisites.
• EnforcementTimeout - Enforcement evaluation exceeded configured timeout budget.
• CredentialInjectionFailed - Sidecar failed to inject credentials for Stage 3.
• ConnectorTimeout - Outbound connector timed out.
• ConnectorNetworkError - Outbound connector failed at the transport layer (DNS, TCP,
• ConnectorInvalidRequest - Outbound connector could not translate the envelope into a
• UnclassifiedIntent - Protected action could not be mapped to any canonical action class.
• TenantMismatch - Token’s agent_id differs from the first agent_id observed by this
• LoopbackBlocked - Agent attempted a direct connection to a loopback address that is not a
• StepUpRequired - AARM R4 STEP_UP: the call is blocked pending human approval or
• Deferred - AARM R4 DEFER: the call is blocked and should be retried after the

Traits: Error, Eq, Copy

Trait Implementations:

• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &DenyReason) -> bool
• Clone
  • fn clone(self: &Self) -> DenyReason
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>

firma_core::decision::ModificationError

Enum

Errors that can arise when parsing or applying a [ModificationSpec].

Variants:

• EmptyValue - The @modify annotation value was empty.
• EmptyHeaderName - The header name in redact_header:<name> was empty.
• InvalidHeaderName{ raw: String, source: http::header::InvalidHeaderName } - The header name could not be parsed as a valid HTTP header name.
• UnknownKind{ value: String } - The @modify kind was not recognised.
• UnsupportedModificationTarget - The transformation targets HTTP headers, but the envelope’s action

Trait Implementations:

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

firma_core::decision::ModificationSpec

Enum

Structured transformation applied to a request under the AARM R4 MODIFY decision.

Sourced from a @modify("…") Cedar policy annotation. The annotation value is a small DSL: <kind>:<value>. V1 supports a single kind:

• redact_header:<name> — strip the named HTTP header (case-insensitive) from the outbound request before dispatch. The audit record carries redacted_header:<name> so an operator can reconcile the transformed execution against policy intent.

redact_header strips the header from the agent-produced request. It does not prevent the sidecar’s credential-injection stage from adding the same header back to the outbound request — the redaction is scoped to what the agent sent, not to what the sidecar injects.

Unknown kinds, empty header names, or an invalid header name reject the bundle at load time — the author must fix the policy. New kinds (e.g. strip_query_param) can be added later as enum variants without a wire break.

Variants:

• RedactHeader(http::HeaderName) - Strip the named HTTP header from the outbound request before dispatch.

Methods:

• fn parse(annotation: &str) -> Result<Self, ModificationError> - Parse a @modify("…") annotation value into a [ModificationSpec].
• fn apply(self: &Self, envelope: & mut crate::envelope::ExecutionEnvelope) -> Result<(), ModificationError> - Apply this transformation in place to a dispatch-bound envelope.

Traits: Eq

Trait Implementations:

• PartialEq
  • fn eq(self: &Self, other: &ModificationSpec) -> bool
• Display
  • fn fmt(self: &Self, f: & mut std::fmt::Formatter) -> std::fmt::Result
• Serialize
  • fn serialize<S>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Deserialize
  • fn deserialize<D>(deserializer: D) -> Result<Self, <D as >::Error>
• Clone
  • fn clone(self: &Self) -> ModificationSpec

firma_core::decision::SecretJsonSelector

Struct

A JSONPath selector whose evaluation root is explicit.

The scope is part of the serialized shape, for example {"path":"$.title","scope":"document"}; scope is never inferred from JSONPath syntax. Cardinality depends on both the selector’s role and its scope: record-scoped item selectors require one match per record, while a document-scoped item selector accepts zero or one match. Domain selectors require one or more valid string matches at every applicable root. See the field docs on [SecretMatcher::Json] for failure behavior.

Fields:

• path: String - JSONPath evaluated at the root selected by [Self::scope].
• scope: SecretJsonSelectorScope - Whether the path is relative to each record or to the whole document.

Traits: Eq

Trait Implementations:

• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• Clone
  • fn clone(self: &Self) -> SecretJsonSelector
• PartialEq
  • fn eq(self: &Self, other: &SecretJsonSelector) -> bool

firma_core::decision::SecretJsonSelectorScope

Enum

Evaluation root for a [SecretJsonSelector].

Variants:

• Record - Evaluate independently against every node selected by record_path.
• Document - Evaluate once against the document root and broadcast the selector results.

Traits: Eq, Copy

Trait Implementations:

• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• PartialEq
  • fn eq(self: &Self, other: &SecretJsonSelectorScope) -> bool
• Clone
  • fn clone(self: &Self) -> SecretJsonSelectorScope

firma_core::decision::SecretMatcher

Enum

How to extract (name, value) pairs from a vault CLI’s stdout or an HTTP vault’s response body.

Defined in IntegrationRegistry built-in specs and optional explicit extractor config; the execution (JSONPath / Regex compilation and rewrite) lives in firma-secret-provider. Internally tagged ({"type": "json", ...} rather than the default {"Json": {...}}) so it nests as a flat table when embedded in TOML (e.g. the Sidecar’s http_secret_providers config) as well as JSON.

Variants:

• Json{ record_path: String, value_path: String, name: SecretNameSource, item_selector: Option<SecretJsonSelector>, domain_selector: Option<SecretJsonSelector> } - JSONPath extraction over structured output.
• Regex{ pattern: String } - Regex extraction over text output. The pattern carries a required

Traits: Eq

Trait Implementations:

• PartialEq
  • fn eq(self: &Self, other: &SecretMatcher) -> bool
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• Clone
  • fn clone(self: &Self) -> SecretMatcher

firma_core::decision::SecretNameSource

Enum

How a JSON record’s secret name is determined.

Most providers store the secret’s name as an explicit string value (e.g. a label or key field) selected by Path. Some providers — e.g. HashiCorp Vault’s kv get -format=json, which returns a flat {name: value, ...} secret map with no separate name field — instead encode the name as the record’s own key in its parent JSON object; use RecordKey when record_path selects records that way.

Variants:

• Path{ path: String } - Record-relative JSONPath selecting the name string, aligned by
• RecordKey - The record’s own key in its parent JSON object — the final segment of

Traits: Eq

Trait Implementations:

• PartialEq
  • fn eq(self: &Self, other: &SecretNameSource) -> bool
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• 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>
• Clone
  • fn clone(self: &Self) -> SecretNameSource

firma_core::decision::StepUpSpec

Struct

Human-readable challenge description for an AARM R4 STEP_UP decision.

Validates at construction that the value is not empty or whitespace-only, so any value that survives into a [crate::DenyReason::StepUpRequired] or a PolicyVerdict::StepUp is guaranteed to carry a meaningful message.

Tuple Struct: ()

Methods:

• fn new<impl Into<String>>(value: impl Trait) -> Result<Self, ModificationError> - Construct a [StepUpSpec] from a challenge string.
• fn as_str(self: &Self) -> &str - Return the challenge description as a &str.

Traits: Eq

Trait Implementations:

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