Slixmpp OMEMO Plugin

https://github.com/syndace/slixmpp-omemo
Admin
A plugin for Slixmpp offering the OMEMO Multi-End Message and Object Encryption protocol (XEP-0384),...
Tokens:34,425
Snippets:237
Trust Score:6.8
License:AGPL-3.0
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Run tests, type checks, and linting

Source: https://github.com/syndace/slixmpp-omemo/blob/main/README.md

Install test and lint dependencies, then run mypy, pylint, flake8, and pytest on the project directories.

```sh
$ pip install --upgrade .[test,lint]
$ mypy slixmpp_omemo/ examples/ tests/
$ pylint slixmpp_omemo/ examples/ tests/
$ flake8 slixmpp_omemo/ examples/ tests/
$ pytest
```

--------------------------------

### Example: decrypt_message with error handling

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Example usage of decrypt_message. It first checks is_encrypted, then attempts decryption, handling SenderNotFound, MessageNotForUs, and other exceptions. Requires omemo.session_manager imports.

```python
from omemo.session_manager import MessageNotForUs, SenderNotFound

namespaces = xep_0384.is_encrypted(stanza)
if not namespaces:
    return  # not encrypted

try:
    message, device = await xep_0384.decrypt_message(stanza)
    print(f"From {device.bare_jid}/{device.device_id}: {message['body']}")
except SenderNotFound as e:
    log.warning(f"Sender device info not available: {e}")
except MessageNotForUs:
    log.info("Message not encrypted for us")
except Exception as e:  # includes ValueError / XMLSchemaValidationError
    log.error(f"Decryption failed: {type(e).__name__}: {e}")
```

--------------------------------

### Subclassing the trust model with XEP_0384

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/base_session_manager.md

Example from examples/echo_client.py showing a user-facing plugin subclass that implements _btbv_enabled and _prompt_manual_trust. The prompt method is normally never called when BTBV is enabled, but provides a manual trust prompt for devices.

```python
from typing import FrozenSet, Optional
from omemo.types import DeviceInformation
from slixmpp_omemo import TrustLevel, XEP_0384

class MyOmemoPlugin(XEP_0384):
    @property
    def _btbv_enabled(self) -> bool:
        return True

    async def _prompt_manual_trust(
        self,
        manually_trusted: FrozenSet[DeviceInformation],
        identifier: Optional[str]
    ) -> None:
        # BTBV is on, so this is normally never called. Implement a manual prompt:
        manager = await self.get_session_manager()
        for device in manually_trusted:
            for answer in iter(lambda: input(f"Trust {device}? (yes/no) "), None):
                if answer in {"yes", "no"}:
                    await manager.set_trust(
                        device.bare_jid,
                        device.identity_key,
                        TrustLevel.TRUSTED.value if answer == "yes" else TrustLevel.DISTRUSTED.value
                    )
                    break
```

--------------------------------

### Example — encrypt and send to one recipient

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Encrypts a chat message for a single recipient and sends it. The EME hint is optional and set after encryption. The returned encrypted stanza is ready to send.

```python
from slixmpp.stanza import Message

stanza = xmpp.make_message(mto="romeo@example.org", mtype="chat")
stanza["body"] = "Hello, Romeo!"

encrypted, errors = await xep_0384.encrypt_message(stanza, JID("romeo@example.org"))
if encrypted is not None:
    encrypted["eme"]["namespace"] = oldmemo.oldmemo.NAMESPACE  # EME hint (optional)
    encrypted.send()
```

--------------------------------

### Example: is_encrypted usage

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Example usage of is_encrypted to check for encryption and handle different namespaces. The possible namespaces are twomemo.twomemo.NAMESPACE (omemo:2) and oldmemo.oldmemo.NAMESPACE (eu.siacs.conversations.axolotl).

```python
namespaces = xep_0384.is_encrypted(stanza)
if len(namespaces) == 0:
    # plaintext or unsupported encryption
    ...
elif oldmemo.oldmemo.NAMESPACE in namespaces:
    ...
```

--------------------------------

### Example — MUC encryption for all participants, with error handling

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Encrypts a groupchat message for all participants, passing an identifier for trust decisions. Handles the case where nothing is encrypted, logs non-critical errors, and catches send failures.

```python
participants = {
    JID(xep_0045.get_jid_property(room_jid, nick, "jid"))
    for nick in xep_0045.get_roster(room_jid)
}

encrypted, errors = await xep_0384.encrypt_message(stanza, participants, identifier="chat-tab-42")

if encrypted is None:
    log.warning("Nothing to encrypt in message")
    return
if errors:
    log.info(f"Non-critical encryption errors: {errors}")

try:
    encrypted.send()
except Exception as e:
    log.error(f"Failed to send encrypted message: {e}")
```

--------------------------------

### session_bind method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Called by Slixmpp when the XMPP session is bound to a JID. Starts asynchronous creation of the session manager via asyncio.create_task.

```python
def session_bind(self, jid: JID) -> None:
```

--------------------------------

### Constructor signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Initializes the plugin, forwarding all arguments to BasePlugin.__init__. Plugin config keys arrive via kwargs. Sets up private state including session manager and MUC reflection cache.

```python
def __init__(self, *args: Any, **kwargs: Any) -> None:
```

--------------------------------

### XEP_0384.plugin_init()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Initializes the XEP-0384 plugin. This method is part of the plugin lifecycle and sets up necessary configurations.

```APIDOC
## [METHOD] XEP_0384.plugin_init()

### Description
Initializes the XEP-0384 plugin.

### Method
Method call

### Endpoint
XEP_0384.plugin_init()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### Package __init__.py re-exports

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/package.md

Complete contents of slixmpp_omemo/__init__.py, re-exporting __version__, TrustLevel, and XEP_0384 for consumers.

```python
from .version import __version__ as __version__

from .base_session_manager import TrustLevel as TrustLevel
from .xep_0384 import XEP_0384 as XEP_0384
```

--------------------------------

### Node-event mapping for twomemo and oldmemo device lists

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/endpoints.md

Maps XMPP PEP node names to internal event names via xep_0060.map_node_event in plugin_init. The twomemo device-list node triggers 'twomemo_device_list' events, and the oldmemo device-list node triggers 'oldmemo_device_list' events.

```text
urn:xmpp:omemo:2:devices                 -> "twomemo_device_list"
eu.siacs.conversations.axolotl.devicelist -> "oldmemo_device_list"
```

--------------------------------

### Custom plugin subclass with config and registration

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/configuration.md

Shows how to subclass XEP_0384, define a custom default_config with an additional json_file_path key, and register the plugin with per-instance config. The plugin reads config keys as attributes on itself.

```python
from slixmpp.plugins import register_plugin
import sys

class XEP_0384Impl(XEP_0384):
    default_config = {
        "fallback_message": "This message is OMEMO encrypted.",
        "json_file_path": None          # subclass-defined option
    }

    def plugin_init(self) -> None:
        if not self.json_file_path:
            raise PluginCouldNotLoad("JSON file path not specified.")
        self.__storage = StorageImpl(Path(self.json_file_path))
        super().plugin_init()

    ...

register_plugin(XEP_0384Impl)

xmpp.register_plugin(
    "xep_0384",
    { "json_file_path": args.json_file_path },   # per-instance config
    module=sys.modules[__name__]
)
```

--------------------------------

### plugin_init method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Called by Slixmpp when the plugin is loaded. Registers event handlers and PEP interest. Subclasses may override to set up storage before calling super().plugin_init().

```python
def plugin_init(self) -> None:
```

--------------------------------

### get_session_manager - retrieve session manager and list devices

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Lazily builds the session manager once using storage and legacy storage, then fires the omemo_initialized event. The first call also runs ensure_data_consistency() and after_history_sync(). Use this to access the core OMEMO interface, e.g., to list devices for a JID.

```python
async def get_session_manager(self) -> SessionManager:
```

```python
xep_0384 = xmpp["xep_0384"]
manager = await xep_0384.get_session_manager()
device_information = await manager.get_device_information("romeo@example.org")
```

--------------------------------

### Import path for public symbols

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/package.md

Shows the recommended import statement for the three public symbols from the top-level package.

```python
from slixmpp_omemo import TrustLevel, XEP_0384, __version__
```

--------------------------------

### Minimal consumer import for plugin registration

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/package.md

Shows the minimal top-level import surface used by consumers to subclass XEP_0384 and register it with Slixmpp.

```python
from slixmpp_omemo import TrustLevel, XEP_0384

# Used to register the plugin with Slixmpp, e.g.:
# xmpp.register_plugin("xep_0384", {...}, module=my_module)
```

--------------------------------

### _btbv_enabled (property)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Abstract property that must be implemented by subclasses to indicate whether Blind Trust Before Verification is enabled.

```APIDOC
## _btbv_enabled (property)

### Description
Abstract property that must be implemented by subclasses to indicate whether Blind Trust Before Verification is enabled.

### Returns
- `bool` - Whether Blind Trust Before Verification is enabled.

### Notes
- Must be implemented.
```

--------------------------------

### _prompt_manual_trust

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Called when the encryption needs a manual trust decision for undecided devices. Must be implemented. Persist decisions via `SessionManager.set_trust`.

```APIDOC
## _prompt_manual_trust

### Description
Called when the encryption needs a manual trust decision for undecided devices. Must be implemented. Persist decisions via `SessionManager.set_trust`.

### Parameters
- `manually_trusted` (FrozenSet[DeviceInformation]) - Set of devices that need a manual trust decision.
- `identifier` (Optional[str]) - Opaque application-specific value passed through from `encrypt_message`.

### Raises
- `TrustDecisionFailed` - From python-omemo if the decision could not be completed; subclasses may raise subclasses instead.

### Contract
- When this returns, all previously undecided trust levels should have been replaced. If they still evaluate to undecided, encryption fails with an exception (see `SessionManager.encrypt`).
```

--------------------------------

### _subscribe(namespace, jid)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Manually subscribe to the device list pubsub node of the JID and track the subscription status.

```APIDOC
## _subscribe(namespace, jid)

### Description
Manually subscribe to the device list pubsub node of the JID and track the subscription status.

### Method
Async method

### Parameters
- **namespace** (str) - Required - The OMEMO version namespace (not the node).
- **jid** (JID) - Required - The JID whose device list to manually subscribe to. Can be a bare (aka “userhost”) JID but doesn’t have to.

### Return Type
None
```

--------------------------------

### version.py __version__ definition

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/package.md

Defines __version__ as "2.2.0" and declares it as the only public symbol of the version module.

```python
__all__ = [ "__version__" ]

__version__ = "2.2.0"
```

--------------------------------

### legacy_storage (property)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Optional property that can be overridden to return a legacy storage backend for migrating data from python-omemo versions older than v1.0.0. The migration is automatic and idempotent.

```APIDOC
## legacy_storage (property)

### Description
Optional property that can be overridden to return a legacy storage backend for migrating data from python-omemo versions older than v1.0.0. The migration is automatic and idempotent.

### Returns
- `Optional[LegacyStorage]` - A legacy storage backend (`oldmemo.migrations.LegacyStorage`) to migrate data from, or `None` (the default).

### Notes
- Override to have the plugin migrate data from python-omemo versions older than v1.0.0.
- The migration is automatic and idempotent (run inside `_prepare` via `oldmemo.migrations.migrate`, resetting trust to at most undecided).
```

--------------------------------

### Default config for XEP_0384 plugin

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/configuration.md

Declares the default_config dictionary for the XEP_0384 plugin, containing the fallback_message key. This is merged with the plugin-config dictionary passed during registration.

```python
default_config = {
    # TODO: Improve fallback text :)
    "fallback_message": "This message is OMEMO encrypted."
}
```

--------------------------------

### XEP_0384._subscribe()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Subscribes to a resource. This method is part of the XEP-0384 plugin and manages subscriptions.

```APIDOC
## [METHOD] XEP_0384._subscribe()

### Description
Subscribes to a resource.

### Method
Method call

### Endpoint
XEP_0384._subscribe()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### _btbv_enabled (property)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Abstract property indicating whether BTBV is enabled.

```APIDOC
## _btbv_enabled (property)

### Description
Abstract property indicating whether BTBV is enabled.

### Returns
- **bool** - Whether BTBV is enabled.
```

--------------------------------

### _devices_blindly_trusted

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Called automatically whenever at least one device was blindly trusted. Use it to notify the user about the automated trust change. Default does nothing; overridable.

```APIDOC
## _devices_blindly_trusted

### Description
Called automatically whenever at least one device was blindly trusted. Use it to notify the user about the automated trust change. Default does nothing; overridable.

### Parameters
- `blindly_trusted` (FrozenSet[DeviceInformation]) - Set of devices (`omemo.types.DeviceInformation`) that were blindly trusted.
- `identifier` (Optional[str]) - Opaque application-specific value passed through from `encrypt_message` (e.g. the chat tab that triggered encryption).

### Notes
- Default: does nothing. Overridable (not abstract).
```

--------------------------------

### XEP_0384._on_device_list_update()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Handles device list updates. This method is part of the XEP-0384 plugin and processes incoming device list changes.

```APIDOC
## [METHOD] XEP_0384._on_device_list_update()

### Description
Handles device list updates.

### Method
Method call

### Endpoint
XEP_0384._on_device_list_update()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### refresh_device_lists - pre-warm device lists for a JID

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Ensures up-to-date device lists are cached for the given JIDs. Called automatically by encrypt_message; call manually to optimize, e.g., when an OMEMO-enabled chat tab opens. Skips the client's own JID and handles manual pubsub subscription when PEP is not enabled.

```python
async def refresh_device_lists(self, jids: Set[JID], force_download: bool = False) -> None:
```

```python
from slixmpp.jid import JID

await xep_0384.refresh_device_lists({ JID("romeo@example.org") })
```

--------------------------------

### _unsubscribe(namespace, jid)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Manually unsubscribe from the device list pubsub node of the JID and track the subscription status.

```APIDOC
## _unsubscribe(namespace, jid)

### Description
Manually unsubscribe from the device list pubsub node of the JID and track the subscription status.

### Method
Async method

### Parameters
- **namespace** (str) - Required - The OMEMO version namespace (not the node).
- **jid** (JID) - Required - The JID whose device list to manually unsubscribe from. Can be a bare (aka “userhost”) JID but doesn’t have to.

### Return Type
None
```

--------------------------------

### XEP_0384.session_bind()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Binds the session for the plugin. This method is part of the plugin lifecycle and handles session binding.

```APIDOC
## [METHOD] XEP_0384.session_bind()

### Description
Binds the session for the plugin.

### Method
Method call

### Endpoint
XEP_0384.session_bind()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### XEP_0384._on_subscription_changed()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Handles subscription changes. This method is part of the XEP-0384 plugin and processes subscription updates.

```APIDOC
## [METHOD] XEP_0384._on_subscription_changed()

### Description
Handles subscription changes.

### Method
Method call

### Endpoint
XEP_0384._on_subscription_changed()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### storage (property)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Abstract property that must be implemented by subclasses to return the Storage implementation used to persist all OMEMO-related data.

```APIDOC
## storage (property)

### Description
Abstract property that must be implemented by subclasses to return the Storage implementation used to persist all OMEMO-related data.

### Returns
- `Storage` - The `omemo.storage.Storage` implementation used to persist all OMEMO-related data.

### Notes
- Must be implemented.
```

--------------------------------

### _prompt_manual_trust(manually_trusted, identifier)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Abstract method to prompt the user for manual trust decisions on a set of undecided identity keys. The trust decisions must be persisted by calling set_trust().

```APIDOC
## _prompt_manual_trust(manually_trusted, identifier)

### Description
Prompt manual trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling `set_trust()`.

### Method
Abstract async method

### Parameters
- **manually_trusted** (FrozenSet[DeviceInformation]) - Required - A set of devices whose trust has to be manually decided by the user.
- **identifier** (str | None) - Required - A piece of application-specific information that callers can pass to `encrypt_message()`, which is then forwarded here unaltered. This can be used, for example, by instant messaging clients, to identify the chat tab which triggered the call to `encrypt_message()` and subsequently this call to `_prompt_manual_trust()`.

### Raises
- **TrustDecisionFailed** - if for any reason the trust decision failed/could not be completed. Feel free to raise a subclass instead.

### Return Type
None

### Note
This is called when the encryption needs to know whether it is allowed to encrypt for these devices or not. When this method returns, all previously undecided trust levels should have been replaced by calling `set_trust()` with a different trust level. If they are not replaced or still evaluate to the undecided trust level after the call, the encryption will fail with an exception. See `encrypt()` for details.
```

--------------------------------

### XEP_0384._unsubscribe()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Unsubscribes from a resource. This method is part of the XEP-0384 plugin and manages subscriptions.

```APIDOC
## [METHOD] XEP_0384._unsubscribe()

### Description
Unsubscribes from a resource.

### Method
Method call

### Endpoint
XEP_0384._unsubscribe()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### XEP_0384.plugin_end()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Finalizes the XEP-0384 plugin. This method is part of the plugin lifecycle and cleans up resources.

```APIDOC
## [METHOD] XEP_0384.plugin_end()

### Description
Finalizes the XEP-0384 plugin.

### Method
Method call

### Endpoint
XEP_0384.plugin_end()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### _on_subscription_changed(presence)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Callback to handle presence subscription changes.

```APIDOC
## _on_subscription_changed(presence)

### Description
Callback to handle presence subscription changes.

### Method
Async method

### Parameters
- **presence** (Presence) - Required - The presence stanza triggering this callback.

### Return Type
None
```

--------------------------------

### refresh_device_lists

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Ensures up-to-date device lists are cached for the given JIDs. It is called automatically by `encrypt_message` but can be called manually for optimization, such as when an OMEMO-enabled chat tab opens.

```APIDOC
## refresh_device_lists

### Description
Ensures up-to-date device lists are cached for the given JIDs. It is called automatically by `encrypt_message` but can be called manually for optimization, such as when an OMEMO-enabled chat tab opens.

### Method
async def refresh_device_lists(self, jids: Set[JID], force_download: bool = False) -> None

### Parameters
- **jids** (Set[JID]) - Required - JIDs whose device lists to refresh (bare or full).
- **force_download** (bool) - Optional - Force downloading even when pubsub/PEP keeps the cache updated automatically.

### Behavior
- Skips the client's own JID.
- If PEP is not enabled for a JID (mutual presence subscription via roster), ensures a manual pubsub subscription exists (`_subscribe`) and marks the affected namespace for a manual refresh.
- If `force_download` is set, all namespaces are refreshed.
- A failed `refresh_device_list` that raises `omemo.DeviceListDownloadFailed` is only debug-logged (device list may not exist yet).

### Raises
- Other exceptions from `SessionManager.refresh_device_lists` are forwarded as-is.

### Example
```python
from slixmpp.jid import JID

await xep_0384.refresh_device_lists({ JID("romeo@example.org") })
```
```

--------------------------------

### Catch errors in consumer code

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/errors.md

Shows how to catch encryption and decryption errors when using the slixmpp-omemo plugin. The encrypt_message call returns a tuple of (encrypted, errors) where errors contains non-critical per-recipient EncryptionError instances. Decryption can raise SenderNotFound, MessageNotForUs, ValueError, or NotImplementedError. Note that BundleDownloadFailed and DeviceListDownloadFailed derive from the python-omemo exception hierarchy, so catch specific classes or their common base rather than module-level names in slixmpp_omemo.

```python
from omemo.session_manager import (
    BundleDownloadFailed, DeviceListDownloadFailed, EncryptionError,
    MessageNotForUs, SenderNotFound, UnknownNamespace,
)

try:
    encrypted, errors = await xep_0384.encrypt_message(stanza, recipient)
    for err in errors:            # non-critical, per-recipient
        if isinstance(err, EncryptionError):
            log.warning(f"Skipped recipient: {err}")
except (ValueError, UnknownNamespace) as e:
    log.error(f"Could not build encrypted stanza: {e}")

try:
    message, device = await xep_0384.decrypt_message(stanza)
except SenderNotFound as e:
    log.warning(f"Unknown sender device: {e}")
except MessageNotForUs:
    log.info("Message not for us")
except ValueError as e:          # malformed stanza, multiple encrypted elements, ...
    log.error(f"Malformed encrypted message: {e}")
except NotImplementedError:
    log.error("Twomemo (SCE) decryption is not supported yet")
```

--------------------------------

### refresh_device_lists(jids, force_download=False)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Ensure that up-to-date device lists for the JIDs are cached. This is done automatically by encrypt_message(), but can be called manually for optimization reasons.

```APIDOC
## refresh_device_lists(jids, force_download=False)

### Description
Ensure that up-to-date device lists for the JIDs are cached. This is done automatically by `encrypt_message()`. You don’t have to ever manually call this method, but you can do so for optimization reasons. For example, in a UI-based IM application, this method can be called when an OMEMO-enabled chat tab/window is opened, to be optimally prepared if the user decides to send an encrypted message.

### Method
Async method

### Parameters
- **jids** (Set[JID]) - Required - The JIDs whose device lists to refresh. Can be bare (aka “userhost”) JIDs but don’t have to.
- **force_download** (bool) - Optional - Force downloading the device list even if pubsub/PEP are enabled to automatically keep the cached device lists up-to-date.

### Raises
- **Exception** - all exceptions raised by `refresh_device_lists()` are forwarded as-is.

### Return Type
None
```

--------------------------------

### XEP_0384._devices_blindly_trusted()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Checks if devices are blindly trusted. This method is part of the XEP-0384 plugin and evaluates trust settings.

```APIDOC
## [METHOD] XEP_0384._devices_blindly_trusted()

### Description
Checks if devices are blindly trusted.

### Method
Method call

### Endpoint
XEP_0384._devices_blindly_trusted()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### plugin_end method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Called when the plugin is unloaded. Removes event handlers and PEP interest, schedules session manager shutdown, and cancels any in-flight build task.

```python
def plugin_end(self) -> None:
```

--------------------------------

### _on_device_list_update(msg)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Callback to handle PEP updates to the device list node of either OMEMO protocol version.

```APIDOC
## _on_device_list_update(msg)

### Description
Callback to handle PEP updates to the device list node of either OMEMO protocol version.

### Method
Async method

### Parameters
- **msg** (Message) - Required - The stanza containing the PEP update event.

### Return Type
None
```

--------------------------------

### BaseSessionManager._make_trust_decision()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Makes a trust decision for a device. This method is part of the BaseSessionManager class and determines trust status.

```APIDOC
## [METHOD] BaseSessionManager._make_trust_decision()

### Description
Makes a trust decision for a device.

### Method
Method call

### Endpoint
BaseSessionManager._make_trust_decision()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### BaseSessionManager._devices_blindly_trusted()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Checks if devices are blindly trusted. This method is part of the BaseSessionManager class and evaluates trust settings.

```APIDOC
## [METHOD] BaseSessionManager._devices_blindly_trusted()

### Description
Checks if devices are blindly trusted.

### Method
Method call

### Endpoint
BaseSessionManager._devices_blindly_trusted()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### get_session_manager

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Retrieves the internally used SessionManager instance, which is the core interface of the underlying OMEMO library. It lazily builds the session manager once and fires the 'omemo_initialized' event after building.

```APIDOC
## get_session_manager

### Description
Retrieves the internally used SessionManager instance, which is the core interface of the underlying OMEMO library. It lazily builds the session manager once and fires the 'omemo_initialized' event after building.

### Method
async def get_session_manager(self) -> SessionManager

### Returns
- **SessionManager**: The `omemo.session_manager.SessionManager` instance internally used by the plugin.

### Behavior
- Lazily builds the session manager exactly once (via `_prepare`) using `self.storage` and `self.legacy_storage`; concurrent callers await the same in-flight build task.
- After building, fires the `omemo_initialized` event.
- The first call also runs `ensure_data_consistency()` and `after_history_sync()`.

### Example
```python
xep_0384 = xmpp["xep_0384"]
manager = await xep_0384.get_session_manager()
device_information = await manager.get_device_information("romeo@example.org")
```
```

--------------------------------

### XEP_0384 class declaration

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Declares the abstract XEP_0384 plugin class extending BasePlugin with ABCMeta metaclass. Must be subclassed and abstract members implemented before registering with Slixmpp.

```python
class XEP_0384(BasePlugin, metaclass=ABCMeta):  # pylint: disable=invalid-name
```

--------------------------------

### _prompt_manual_trust(manually_trusted, identifier)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Prompts manual trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust(). Raises TrustDecisionFailed if the trust decision fails.

```APIDOC
## _prompt_manual_trust(manually_trusted, identifier)

### Description
Prompts manual trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust(). Raises TrustDecisionFailed if the trust decision fails.

### Method
async abstract method

### Parameters
- **manually_trusted** (FrozenSet[DeviceInformation]) - Required - A set of devices whose trust has to be manually decided by the user.
- **identifier** (str | None) - Required - Forwarded from _make_trust_decision(), refer to its documentation for details.

### Returns
None

### Raises
- **TrustDecisionFailed** - if for any reason the trust decision failed/could not be completed.
```

--------------------------------

### _devices_blindly_trusted(blindly_trusted, identifier)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Notifies about newly blindly trusted devices. Called automatically by _make_trust_decision() whenever at least one device was blindly trusted. Does nothing by default.

```APIDOC
## _devices_blindly_trusted(blindly_trusted, identifier)

### Description
Notifies about newly blindly trusted devices. Called automatically by _make_trust_decision() whenever at least one device was blindly trusted. Does nothing by default.

### Method
async method

### Parameters
- **blindly_trusted** (FrozenSet[DeviceInformation]) - Required - A set of devices that were blindly trusted.
- **identifier** (str | None) - Required - Forwarded from _make_trust_decision(), refer to its documentation for details.

### Returns
None
```

--------------------------------

### encrypt_message

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Encrypts a message stanza, selecting the optimal OMEMO protocol version per recipient device (twomemo encrypts the whole stanza via SCE; oldmemo encrypts only the body). Returns a copy of the input stanza ready to be sent, along with any non-critical encryption errors.

```APIDOC
## [Python] encrypt_message

### Description
Encrypts a message stanza, selecting the optimal OMEMO protocol version per recipient device (twomemo encrypts the whole stanza via SCE; oldmemo encrypts only the body). Returns a copy of the input stanza ready to be sent, along with any non-critical encryption errors.

### Method
Python async function

### Signature
```python
async def encrypt_message(
    self,
    stanza: Message,
    recipient_jids: Union[JID, Set[JID]],
    identifier: Optional[str] = None
) -> Tuple[Optional[Message], FrozenSet[EncryptionError]]:
```

### Parameters
- **stanza** (Message) - Required - The stanza to encrypt. Must be associated with an XML stream that has message ids enabled (otherwise `ValueError`).
- **recipient_jids** (Union[JID, Set[JID]]) - Required - A single JID or a set of JIDs (bare or full). Must be non-empty.
- **identifier** (Optional[str]) - Optional - Opaque value forwarded to `_devices_blindly_trusted`/`_prompt_manual_trust` if a trust decision is needed; passed through unaltered.

### Returns
- **message** (Optional[Message]) - A copy of the input stanza, cleared and rebuilt with the fallback body (`self.fallback_message`), the store hint enabled, the same message id, and one serialized OMEMO element per used namespace — ready to be sent. `None` when there is nothing to send (e.g. the input has no body and all recipients would need oldmemo).
- **encryption_errors** (FrozenSet[EncryptionError]) - A frozen set of non-critical `omemo.session_manager.EncryptionError`s encountered during encryption.

### Raises
- `ValueError` if `recipient_jids` is empty.
- `ValueError` if the stanza has no XML stream or the stream does not have `use_message_ids` enabled.
- `UnknownNamespace` if a returned message's namespace cannot be serialized.
- All exceptions from `SessionManager.encrypt` are forwarded (e.g. trust-decision failures).

### Notes
- For groupchat stanzas, the plaintexts are cached by stanza id in `__muc_reflection_cache` so the client's own MUC reflection can later be decrypted from the cache.
- Encrypted stanzas contain only the OMEMO element(s) and store hint; other elements such as read markers are lost for oldmemo (no SCE) and must be re-added manually if desired.
- Messages without a body are not considered for oldmemo encryption.

### Example — encrypt and send to one recipient
```python
from slixmpp.stanza import Message

stanza = xmpp.make_message(mto="romeo@example.org", mtype="chat")
stanza["body"] = "Hello, Romeo!"

encrypted, errors = await xep_0384.encrypt_message(stanza, JID("romeo@example.org"))
if encrypted is not None:
    encrypted["eme"]["namespace"] = oldmemo.oldmemo.NAMESPACE  # EME hint (optional)
    encrypted.send()
```

### Example — MUC encryption for all participants, with error handling
```python
participants = {
    JID(xep_0045.get_jid_property(room_jid, nick, "jid"))
    for nick in xep_0045.get_roster(room_jid)
}

encrypted, errors = await xep_0384.encrypt_message(stanza, participants, identifier="chat-tab-42")

if encrypted is None:
    log.warning("Nothing to encrypt in message")
    return
if errors:
    log.info(f"Non-critical encryption errors: {errors}")

try:
    encrypted.send()
except Exception as e:
    log.error(f"Failed to send encrypted message: {e}")
```
```

--------------------------------

### XEP_0384.refresh_device_lists()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/index.rst

Refreshes the device lists for all contacts. This method is part of the XEP_0384 plugin and is used to update the device information for encryption.

```APIDOC
## XEP_0384.refresh_device_lists()

### Description
Refreshes the device lists for all contacts. This method is part of the XEP_0384 plugin and is used to update the device information for encryption.

### Method
`refresh_device_lists()`

### Parameters
None

### Returns
None
```

--------------------------------

### Public exports of base_session_manager

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/base_session_manager.md

Lists the public exports of the module: TrustLevel and BaseSessionManager.

```python
__all__ = [
    "TrustLevel",
    "BaseSessionManager"
]
```

--------------------------------

### XEP_0384.refresh_device_lists()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Refreshes the device lists for contacts. This method is part of the XEP-0384 plugin and updates the stored device information.

```APIDOC
## [METHOD] XEP_0384.refresh_device_lists()

### Description
Refreshes the device lists for contacts.

### Method
Method call

### Endpoint
XEP_0384.refresh_device_lists()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### XEP_0384.get_session_manager()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/index.rst

Retrieves the session manager instance for the plugin. This method is part of the XEP_0384 plugin and is used to access the session management functionality.

```APIDOC
## XEP_0384.get_session_manager()

### Description
Retrieves the session manager instance for the plugin. This method is part of the XEP_0384 plugin and is used to access the session management functionality.

### Method
`get_session_manager()`

### Parameters
None

### Returns
- **session_manager** (BaseSessionManager) - The session manager instance.
```

--------------------------------

### Import error classes from omemo.session_manager

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/errors.md

Imports the error classes and SessionManager from the python-omemo library. These are the primary exceptions surfaced by slixmpp-omemo, raised with its own messages.

```python
from omemo.session_manager import EncryptionError, SessionManager
from omemo.session_manager import (
    BundleDeletionFailed,
    BundleDownloadFailed,
    BundleNotFound,
    BundleUploadFailed,
    DeviceListDownloadFailed,
    DeviceListUploadFailed,
    MessageNotForUs,
    MessageSendingFailed,
    SenderNotFound,
    UnknownNamespace
)
```

--------------------------------

### BaseSessionManager._evaluate_custom_trust_level()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Evaluates a custom trust level for a device. This method is part of the BaseSessionManager class and handles custom trust evaluation.

```APIDOC
## [METHOD] BaseSessionManager._evaluate_custom_trust_level()

### Description
Evaluates a custom trust level for a device.

### Method
Method call

### Endpoint
BaseSessionManager._evaluate_custom_trust_level()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### get_session_manager()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Access the session manager, which is the main interface to the underlying OMEMO library. A lot of useful functionality is available on the session manager.

```APIDOC
## get_session_manager()

### Description
Access the session manager, which is the main interface to the underlying OMEMO library. A lot of useful functionality is available on the session manager, refer to the library’s API Documentation for details.

### Method
Async method

### Returns
The session manager instance that is internally used by this plugin.

### Return Type
SessionManager
```

--------------------------------

### async encrypt_message(stanza, recipient_jids, identifier=None)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/xep_0384.rst

Encrypts a message stanza for the given recipients, selecting the optimal OMEMO protocol version for each device. Returns the encrypted message and any non-critical errors encountered.

```APIDOC
## async encrypt_message(stanza, recipient_jids, identifier=None)

### Description
Encrypts a message stanza for the given recipients, selecting the optimal OMEMO protocol version for each device. Returns the encrypted message and any non-critical errors encountered.

### Method
async function

### Parameters
- **stanza** (Message) - Required - The stanza to encrypt. Must be associated with an XML stream that has message ids enabled.
- **recipient_jids** (JID | Set[JID]) - Required - The JID of the recipients. Can be bare (aka "userhost") JIDs but doesn't have to. A single JID can be used.
- **identifier** (str | None) - Optional - A value passed to `_devices_blindly_trusted()` and `_prompt_manual_trust()` in case a trust decision is required. Not processed or altered.

### Returns
- **Tuple[Message | None, FrozenSet[EncryptionError]]** - The encrypted message ready to be sent, and a set of non-critical errors. Returns None if there is nothing to be sent (e.g., no body and oldmemo used).

### Raises
- **Exception** - All exceptions raised by `encrypt()` are forwarded as-is.

### Notes
- Encrypted stanzas contain only the bare minimum: OMEMO element(s) and store hint. For SCE versions, other tags are included in the encrypted element; for older versions, only the body is encrypted.
- Messages without a body are not considered for oldmemo encryption.
```

--------------------------------

### encrypt_message method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Signature of the encrypt_message coroutine. Requires the stanza to be associated with an XML stream that has message ids enabled, otherwise ValueError is raised. recipient_jids must be non-empty.

```python
async def encrypt_message(
    self,
    stanza: Message,
    recipient_jids: Union[JID, Set[JID]],
    identifier: Optional[str] = None
) -> Tuple[Optional[Message], FrozenSet[EncryptionError]]:
```

--------------------------------

### XEP_0384 module __all__ export

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Declares the single public name exported by the slixmpp_omemo.xep_0384 module. The XEP_0384 class is also re-exported from the top-level package via 'from slixmpp_omemo import XEP_0384'.

```python
__all__ = [
    "XEP_0384"
]
```

--------------------------------

### TrustLevel Enum

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Enumeration of trust levels used in the BaseSessionManager, including TRUSTED, BLINDLY_TRUSTED, UNDECIDED, and DISTRUSTED.

```APIDOC
## TrustLevel Enum

### Description
Enumeration of trust levels used in the BaseSessionManager, including TRUSTED, BLINDLY_TRUSTED, UNDECIDED, and DISTRUSTED.

### Values
- **TRUSTED** (string) - Trusted device, encryption/decryption allowed.
- **BLINDLY_TRUSTED** (string) - Blindly trusted device.
- **UNDECIDED** (string) - Trust decision pending.
- **DISTRUSTED** (string) - Explicitly not trusted.
```

--------------------------------

### _make_trust_decision(undecided, identifier)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Makes a trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust(). Raises TrustDecisionFailed if the trust decision fails.

```APIDOC
## _make_trust_decision(undecided, identifier)

### Description
Makes a trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust(). Raises TrustDecisionFailed if the trust decision fails.

### Method
async method

### Parameters
- **undecided** (FrozenSet[DeviceInformation]) - Required - A set of devices that require trust decisions.
- **identifier** (str | None) - Required - A piece of application-specific information that callers can pass to encrypt(), which is then forwarded here unaltered.

### Returns
None

### Raises
- **TrustDecisionFailed** - if for any reason the trust decision failed/could not be completed.
```

--------------------------------

### XEP_0384.encrypt_message()

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/package.rst

Encrypts a message for a recipient using OMEMO encryption. This method is part of the XEP-0384 plugin and handles the encryption of message content.

```APIDOC
## [METHOD] XEP_0384.encrypt_message()

### Description
Encrypts a message for a recipient using OMEMO encryption.

### Method
Method call

### Endpoint
XEP_0384.encrypt_message()

### Parameters
No parameters documented.

### Request Example
No request example documented.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example documented.
```

--------------------------------

### is_encrypted method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Signature of the is_encrypted method. It inspects a stanza and returns a set of namespaces of the OMEMO versions the message is encrypted with, or an empty set if not encrypted.

```python
def is_encrypted(self, stanza: Message) -> Set[str]:
```

--------------------------------

### _evaluate_custom_trust_level(device)

Source: https://github.com/syndace/slixmpp-omemo/blob/main/docs/slixmpp_omemo/base_session_manager.rst

Evaluates a custom trust level to one of the three core trust levels: TRUSTED, DISTRUSTED, or UNDECIDED. Raises UnknownTrustLevel if the custom trust level is not known.

```APIDOC
## _evaluate_custom_trust_level(device)

### Description
Evaluates a custom trust level to one of the three core trust levels: TRUSTED, DISTRUSTED, or UNDECIDED. Raises UnknownTrustLevel if the custom trust level is not known.

### Method
async method

### Parameters
- **device** (DeviceInformation) - Required - Information about the device, including the custom trust level name to translate.

### Returns
- **TrustLevel** - The core trust level corresponding to the custom trust level.

### Raises
- **UnknownTrustLevel** - if a custom trust level with this name is not known.
```

--------------------------------

### decrypt_message method signature

Source: https://github.com/syndace/slixmpp-omemo/blob/main/_autodocs/api-reference/xep_0384.md

Signature of the decrypt_message method. It decrypts an OMEMO-encrypted message stanza and returns a tuple of the decrypted stanza and device information. The original stanza is not modified.

```python
async def decrypt_message(self, stanza: Message) -> Tuple[Message, DeviceInformation]:
```
Tokens:
Raw