decision

Module: decision

Contents

Structs

• DeferDuration - Backoff duration for an AARM R4 DEFER decision.
• 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

---

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.

Methods:

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

Traits: Error, Eq, Copy

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

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:

• 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
• 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>

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:

• PartialEq
  • fn eq(self: &Self, other: &DeferDuration) -> bool
• Clone
  • fn clone(self: &Self) -> DeferDuration
• 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::DenyReason

Enum

Typed reason code explaining why a request was denied.

Backlog variants (add back when corresponding mechanisms exist):

• BudgetExceeded — when budget tracking mechanism is designed
• 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:

• 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
• PartialEq
  • fn eq(self: &Self, other: &DenyReason) -> bool
• Clone
  • fn clone(self: &Self) -> DenyReason

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:

• 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>
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

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:

• 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
• PartialEq
  • fn eq(self: &Self, other: &ModificationSpec) -> bool

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:

• 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
• PartialEq
  • fn eq(self: &Self, other: &StepUpSpec) -> bool