Skip to content
OpenFirma OpenFirma
Blog

envelope

Module: envelope

Section titled “Module: envelope”

Contents

Section titled “Contents”

Structs

Enums

  • ActionParams - Typed action parameters (maps to the proto oneof params).
  • HttpMethod - HTTP methods that can appear in an outbound request.

firma_core::envelope::ActionParams

Section titled “firma_core::envelope::ActionParams”

Enum

Typed action parameters (maps to the proto oneof params).

Uses an enum with typed variants to prevent injection via untyped maps.

Variants:

  • Http(HttpParams) - Outbound HTTP request.
  • DbQuery(DbQueryParams) - Database query.
  • ToolUse(ToolUseParams) - Tool/function invocation.

Traits: Eq

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ActionParams
  • PartialEq
    • fn eq(self: &Self, other: &ActionParams) -> 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

firma_core::envelope::DbQueryParams

Section titled “firma_core::envelope::DbQueryParams”

Struct

Parameters for a database query.

Uses a named query plus bindings instead of a raw SQL statement, aligning with the intent-003 proto definition and preventing raw SQL injection at the type level.

Fields:

  • query_name: String - Registered query name (looked up in a query registry).
  • bindings: std::collections::HashMap<String, String> - Bound parameters — scalar values only, keyed by placeholder name.
  • db_name: String - Target database name.
  • read_only: bool - Hint for policy: is this a read-only query?

Traits: Eq

Trait Implementations:

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

firma_core::envelope::ExecutionContext

Section titled “firma_core::envelope::ExecutionContext”

Struct

Flattened attribute set consumed by policy evaluation (Stage 2).

Built from ExecutionEnvelope fields plus Sidecar-local state. The derivation of action and resource from the envelope’s intent is Sidecar-specific logic (added in intent 006).

Fields:

  • agent_id: crate::agent::AgentId - Agent identity, from envelope metadata.
  • action: String - Derived action string (e.g., http:GET, tool:execute).
  • resource: String - Target resource derived from intent (e.g., URL, DB name, tool name).
  • session_id: crate::session::SessionId - Session ID, from envelope metadata.
  • token_id: crate::token::TokenId - Token ID, from parsed capability claims.
  • token_actions: Vec<String> - Allowed actions from capability claims, for scope checks.
  • token_resources: Vec<String> - Allowed resources from capability claims, for scope checks.

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

firma_core::envelope::ExecutionEnvelope

Section titled “firma_core::envelope::ExecutionEnvelope”

Struct

The core protocol unit wrapping each outbound agent call.

Built by the Sidecar when intercepting an agent’s request. Contains the typed action intent, the raw capability token, metadata, and provenance. Immutable once created — any enrichment produces a derived structure.

Fields:

  • intent: ExecutionIntent - Typed action parameters describing what the agent wants to do.
  • capability: String - Raw signed token string. Parsing happens in Stage 1 of the enforcement pipeline.
  • metadata: ExecutionMetadata - Session and runtime metadata for correlation and audit.
  • provenance: Option<String> - Schema-reserved provenance field. V1 does not populate this.

Methods:

  • fn new(intent: ExecutionIntent, capability: String, metadata: ExecutionMetadata, provenance: Option<String>) -> Self - Constructs a new ExecutionEnvelope.
  • fn intent(self: &Self) -> &ExecutionIntent - Gets the typed action parameters describing what the agent wants to do.
  • fn capability(self: &Self) -> &str - Gets the raw signed token string.
  • fn metadata(self: &Self) -> &ExecutionMetadata - Gets the session and runtime metadata for correlation and audit.
  • fn provenance(self: &Self) -> Option<&str> - Gets the schema-reserved provenance field.

Trait Implementations:

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

firma_core::envelope::ExecutionIntent

Section titled “firma_core::envelope::ExecutionIntent”

Struct

Typed description of the action an agent intends to perform.

Contains five canonical intent sub-fields: action_class, resource, params, raw_transport, and raw_action_ref. The action_class is the canonical class from the v0.1 Action Class Registry, set by the Sidecar’s intent normalizer after mapping the raw intercepted request.

Fields:

  • action_class: String - Canonical action class from the v0.1 registry (e.g.,
  • resource: std::collections::BTreeMap<String, String> - Target resource identifier as a structured attribute map.
  • params: ActionParams - Typed action parameters — exactly one action kind per intent.
  • raw_transport: String - Original transport protocol (e.g., "http", "https").
  • raw_action_ref: String - Original request signature for traceability (e.g., "POST /v1/chat/completions").

Methods:

  • fn resource_display(self: &Self) -> String - Derive a display / scope-check string from the resource map.
  • fn resource_map_from(host_path: &str) -> BTreeMap<String, String> - Build a resource map from a display-form string host[/path].

Traits: Eq

Trait Implementations:

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

firma_core::envelope::ExecutionMetadata

Section titled “firma_core::envelope::ExecutionMetadata”

Struct

Session and runtime context attached to every execution envelope.

Fields:

  • session_id: crate::session::SessionId - Session this request belongs to.
  • agent_id: crate::agent::AgentId - Agent that initiated this request.
  • timestamp: chrono::DateTime<chrono::Utc> - When the request was intercepted.
  • trace_id: Option<String> - Optional distributed tracing correlation ID.
  • budget_consumed: f64 - Cumulative budget consumed in this session (e.g., API cost in USD).
  • risk_score: Option<f64> - Static or pre-computed risk attribute. Defaults to None.

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • PartialEq
    • fn eq(self: &Self, other: &ExecutionMetadata) -> bool
  • 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) -> ExecutionMetadata

firma_core::envelope::HttpMethod

Section titled “firma_core::envelope::HttpMethod”

Enum

HTTP methods that can appear in an outbound request.

Restricts the method to known values so that invalid strings (e.g., "WHATEVER") are rejected at the type level.

Variants:

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS
  • CONNECT

Methods:

  • fn as_str(self: Self) -> &'static str - Stable static label used by structured logs and metrics.

Traits: Eq, Copy

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • PartialEq
    • fn eq(self: &Self, other: &HttpMethod) -> bool
  • Clone
    • fn clone(self: &Self) -> HttpMethod
  • Display
    • fn fmt(self: &Self, f: & mut fmt::Formatter) -> 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

firma_core::envelope::HttpParams

Section titled “firma_core::envelope::HttpParams”

Struct

Parameters for an outbound HTTP request.

The target URL lives on ExecutionIntent.resource, not here — matching the proto where HttpParams carries method, headers, body, and query.

Fields:

  • method: HttpMethod - HTTP method.
  • headers: std::collections::HashMap<String, String> - HTTP headers — allowlisted keys only.
  • body: Option<Vec<u8>> - Request body as raw bytes (empty for GET/DELETE).
  • query: std::collections::HashMap<String, String> - Query parameters.

Traits: Eq

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> HttpParams
  • PartialEq
    • fn eq(self: &Self, other: &HttpParams) -> 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

firma_core::envelope::ToolUseParams

Section titled “firma_core::envelope::ToolUseParams”

Struct

Parameters for a tool/function invocation.

Input is a flat String → String map (scalar values only), schema-validated against the tool registry. Aligns with the intent-003 proto definition and keeps the core→proto conversion trivial.

Fields:

  • tool_name: String - Name of the tool to invoke.
  • input: std::collections::HashMap<String, String> - Scalar tool inputs, validated against the tool registry schema.

Traits: Eq

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ToolUseParams
  • PartialEq
    • fn eq(self: &Self, other: &ToolUseParams) -> 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