# `ExWapp.Message.Handler.Inbound.Envelope`
[🔗](https://github.com/elchemista/ex_wapp/blob/v0.1.5/lib/ex_wapp/message/handler/inbound/envelope.ex#L1)

Inbound envelope normalization and sender/payload candidate resolution.

This boundary owns PN/LID envelope mappings, observed-device persistence,
local-recipient matching, and deterministic decrypt candidate construction.
Signal decryption and message-content decoding remain outside this module.

# `decrypt_context`

```elixir
@type decrypt_context() :: %{
  sender_candidates: [String.t()],
  payload_candidates: [payload_candidate()],
  decryptable_payloads: [payload_candidate()]
}
```

# `payload_candidate`

```elixir
@type payload_candidate() :: %{
  optional(:enc_type) => term(),
  optional(:enc_version) => term(),
  optional(:enc_count) => term(),
  optional(:enc_state) => term(),
  optional(:ciphertext) => term(),
  optional(:to_jid) => term()
}
```

# `decrypt_context`

```elixir
@spec decrypt_context(map(), map(), term(), term(), map()) :: decrypt_context()
```

Builds ordered sender and encrypted-payload candidates for Signal decrypt.

# `from_me?`

```elixir
@spec from_me?(map(), term(), map(), map()) :: boolean()
```

Determines whether an inbound envelope represents a local outgoing message.

# `local_recipient_jids`

```elixir
@spec local_recipient_jids(map(), map()) :: [String.t()]
```

Returns normalized local PN/LID recipient identities from state and envelope attributes.

# `own_sender?`

```elixir
@spec own_sender?(map(), term(), term(), map()) :: boolean()
```

Returns whether a server-attested envelope sender belongs to the local account.

Group stanzas use `participant` as the actual sender; direct stanzas fall back
to `from`. Both PN and LID identities, with or without a device suffix, are
accepted. This predicate deliberately ignores message payload claims such as
`from_me` because self-only protocol messages must be authorized from envelope
metadata before their contents are applied.

# `persist_lid_mappings`

```elixir
@spec persist_lid_mappings(map(), map(), term(), term()) :: map()
```

Persists PN/LID pairs observed on an inbound message envelope.

# `persist_observed_devices`

```elixir
@spec persist_observed_devices(map(), map(), term(), term()) :: :ok
```

Persists device JIDs observed in the inbound envelope.

---

*Consult [api-reference.md](api-reference.md) for complete listing*