Jido.Messaging.Security behaviour (Jido Messaging v1.0.0)

Centralized security boundary for inbound verification and outbound sanitization.

Security checks are bounded with timeout budgets, failures are classified, and explicit policy determines whether failures deny or degrade.

Summary

Types

classification()

Security classification for decisions and failures.

decision()

Security decision metadata.

mode()

Security enforcement mode.

sanitize_failure_policy()

Policy for sanitize failures.

sanitize_result()

Successful sanitize result envelope.

security_denial()

Typed security denial returned to ingest/outbound callers.

stage()

Security boundary stage.

verify_failure_policy()

Policy for verify failures.

verify_result()

Successful verify result envelope.

Callbacks

sanitize_outbound(channel_module, outbound, opts)

verify_sender(channel_module, incoming_message, raw_payload, opts)

Functions

config(instance_module, opts \\ [])

Resolve runtime security config for an instance module.

sanitize_outbound(instance_module, channel_module, outbound, opts \\ [])

Sanitize outbound payload through the configured security adapter.

verify_sender(instance_module, channel_module, incoming_message, raw_payload, opts \\ [])

Verify an inbound sender through the configured security adapter.

Types

classification()

@type classification() :: :allow | :deny | :retry | :degrade

Security classification for decisions and failures.

decision()

@type decision() :: %{
  :stage => stage(),
  :classification => classification(),
  :outcome => atom(),
  :action => atom(),
  :policy => atom(),
  :channel => module(),
  :adapter => module(),
  :mode => mode(),
  :elapsed_ms => non_neg_integer(),
  optional(:reason) => term(),
  optional(:description) => String.t(),
  optional(:changed) => boolean(),
  optional(:fallback) => boolean()
}

Security decision metadata.

mode()

@type mode() :: :permissive | :strict

Security enforcement mode.

sanitize_failure_policy()

@type sanitize_failure_policy() :: :allow_original | :deny

Policy for sanitize failures.

sanitize_result()

@type sanitize_result() ::
  {:ok, term(), %{decision: decision(), metadata: map()}}
  | {:error, security_denial()}

Successful sanitize result envelope.

security_denial()

@type security_denial() :: {:security_denied, stage(), atom() | tuple(), String.t()}

Typed security denial returned to ingest/outbound callers.

stage()

@type stage() :: :verify | :sanitize

Security boundary stage.

verify_failure_policy()

@type verify_failure_policy() :: :allow | :deny

Policy for verify failures.

verify_result()

@type verify_result() ::
  {:ok, %{decision: decision(), metadata: map()}} | {:error, security_denial()}

Successful verify result envelope.

Callbacks

sanitize_outbound(channel_module, outbound, opts)

@callback sanitize_outbound(
  channel_module :: module(),
  outbound :: term(),
  opts :: keyword()
) ::
  {:ok, term()} | {:ok, term(), map()} | {:error, term()}

verify_sender(channel_module, incoming_message, raw_payload, opts)

@callback verify_sender(
  channel_module :: module(),
  incoming_message :: map(),
  raw_payload :: map(),
  opts :: keyword()
) :: :ok | {:ok, map()} | {:deny, atom(), String.t()} | {:error, term()}

Functions

config(instance_module, opts \\ [])

@spec config(
  module(),
  keyword()
) :: keyword()

Resolve runtime security config for an instance module.

Config precedence (lowest to highest):

Defaults
config :jido_messaging, :security, ...
config <instance_module>, :security, ...
Runtime overrides passed as security: [...] in opts

sanitize_outbound(instance_module, channel_module, outbound, opts \\ [])

@spec sanitize_outbound(module(), module(), term(), keyword()) :: sanitize_result()

Sanitize outbound payload through the configured security adapter.

verify_sender(instance_module, channel_module, incoming_message, raw_payload, opts \\ [])

@spec verify_sender(module(), module(), map(), map(), keyword()) :: verify_result()

Verify an inbound sender through the configured security adapter.