New: Threema Integration

.strict-typing

@@ -550,6 +550,7 @@ homeassistant.components.telegram_bot.*
 homeassistant.components.teslemetry.*
 homeassistant.components.text.*
 homeassistant.components.thethingsnetwork.*
+homeassistant.components.threema.*
 homeassistant.components.threshold.*
 homeassistant.components.tibber.*
 homeassistant.components.tile.*

homeassistant/components/threema/README.md

@@ -0,0 +1,37 @@
+# Threema Integration
+
+Threema Gateway integration for Home Assistant. Sends E2E encrypted or simple text messages via the [Threema Gateway](https://gateway.threema.ch/) service.
+
+User-facing documentation: https://www.home-assistant.io/integrations/threema
+
+## Architecture
+
+- **`__init__.py`** — Service registration (`threema.send_message`), config entry setup/unload, credential validation on startup
+- **`client.py`** — `ThreemaAPIClient` wrapping the [threema.gateway SDK](https://github.com/threema-ch/threema-msgapi-sdk-python). Handles E2E (`TextMessage`) and simple (`SimpleTextMessage`) modes. Custom exceptions: `ThreemaAuthError`, `ThreemaConnectionError`, `ThreemaSendError`
+- **`config_flow.py`** — Multi-step flow: setup type selection, optional key generation, credential entry with validation, reauthentication
+- **`image.py`** — QR code image entity for gateway identity verification (encodes `3mid:<gateway_id>,<public_key_hex>`)
+- **`const.py`** — Domain and config key constants
+
+## Dependencies
+
+- `threema.gateway==8.0.0` — [Official Threema Gateway SDK](https://github.com/threema-ch/threema-msgapi-sdk-python) (MIT)
+- `qrcode==8.2` — QR code generation for identity verification
+
+## Design Decisions
+
+- **No notify entity** — `NotifyEntity.async_send_message` only accepts `message` and `title`, no recipient parameter. Threema always requires an explicit recipient, so the custom `threema.send_message` service is the proper interface.
+- **Encryption downgrade protection** — Reauth flow preserves existing private keys when the field is left empty, preventing silent downgrade from E2E to simple mode.
+- **Recipient validation** — Service schema validates Threema IDs with `^[0-9A-Za-z]{8}$` regex and normalizes to uppercase.
+- **Multiple entry guard** — Auto-select is rejected when multiple entries are loaded; caller must specify `config_entry_id`.
+
+## Quality Scale
+
+Silver. See `quality_scale.yaml` for full status. Gold blockers: `diagnostics` and `reconfiguration-flow`.
+
+## Roadmap
+
+- Incoming messages via Gateway callback webhooks
+- Image/file support
+- Remaining credits sensor
+- Diagnostics platform
+- Reconfiguration flow

homeassistant/components/threema/__init__.py

@@ -0,0 +1,158 @@
+"""The Threema Gateway integration."""
+
+from __future__ import annotations
+
+import logging
+
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigEntry, ConfigEntryState
+from homeassistant.const import Platform
+from homeassistant.core import HomeAssistant, ServiceCall
+from homeassistant.exceptions import (
+    ConfigEntryAuthFailed,
+    ConfigEntryNotReady,
+    HomeAssistantError,
+    ServiceValidationError,
+)
+from homeassistant.helpers import config_validation as cv
+from homeassistant.helpers.typing import ConfigType
+
+from .client import (
+    ThreemaAPIClient,
+    ThreemaAuthError,
+    ThreemaConnectionError,
+    ThreemaSendError,
+)
+from .const import CONF_API_SECRET, CONF_GATEWAY_ID, CONF_PRIVATE_KEY, DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
+PLATFORMS: list[Platform] = [Platform.IMAGE]
+
+type ThreemaConfigEntry = ConfigEntry[ThreemaAPIClient]
+
+CONF_CONFIG_ENTRY_ID = "config_entry_id"
+CONF_RECIPIENT = "recipient"
+CONF_MESSAGE = "message"
+
+RECIPIENT_SCHEMA = vol.All(
+    cv.string,
+    cv.matches_regex(r"^[0-9A-Za-z]{8}$"),
+    lambda value: value.upper(),
+)
+
+SERVICE_SEND_MESSAGE = "send_message"
+SERVICE_SEND_MESSAGE_SCHEMA = vol.Schema(
+    {
+        vol.Optional(CONF_CONFIG_ENTRY_ID): cv.string,
+        vol.Required(CONF_RECIPIENT): RECIPIENT_SCHEMA,
+        vol.Required(CONF_MESSAGE): cv.string,
+    }
+)
+
+
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
+    """Set up the Threema Gateway component."""
+
+    async def async_send_message(call: ServiceCall) -> None:
+        """Handle the send_message service call."""
+        recipient = call.data[CONF_RECIPIENT]
+        message = call.data[CONF_MESSAGE]
+
+        # Get the config entry - auto-select if not specified
+        entry_id = call.data.get(CONF_CONFIG_ENTRY_ID)
+
+        if entry_id:
+            entry = hass.config_entries.async_get_entry(entry_id)
+            if not entry or entry.domain != DOMAIN:
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="entry_not_found",
+                )
+            if entry.state is not ConfigEntryState.LOADED:
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="entry_not_loaded",
+                )
+        else:
+            # Auto-select: find any loaded Threema config entry
+            entries = [
+                e
+                for e in hass.config_entries.async_entries(DOMAIN)
+                if e.state is ConfigEntryState.LOADED
+            ]
+            if not entries:
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="no_entries_found",
+                )
+            if len(entries) > 1:
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="multiple_entries_found",
+                )
+            entry = entries[0]
+
+        # Send the message
+        client: ThreemaAPIClient = entry.runtime_data
+        try:
+            await client.send_text_message(recipient, message)
+        except ThreemaAuthError as err:
+            _LOGGER.warning(
+                "Authentication failed sending message; check your Gateway credentials"
+            )
+            raise HomeAssistantError(
+                translation_domain=DOMAIN,
+                translation_key="send_error",
+                translation_placeholders={"error": str(err)},
+            ) from err
+        except (ThreemaSendError, ThreemaConnectionError) as err:
+            raise HomeAssistantError(
+                translation_domain=DOMAIN,
+                translation_key="send_error",
+                translation_placeholders={"error": str(err)},
+            ) from err
+
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_SEND_MESSAGE,
+        async_send_message,
+        schema=SERVICE_SEND_MESSAGE_SCHEMA,
+    )
+
+    return True
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ThreemaConfigEntry) -> bool:
+    """Set up Threema Gateway from a config entry."""
+    client = ThreemaAPIClient(
+        hass,
+        gateway_id=entry.data[CONF_GATEWAY_ID],
+        api_secret=entry.data[CONF_API_SECRET],
+        private_key=entry.data.get(CONF_PRIVATE_KEY),
+    )
+
+    try:
+        await client.validate_credentials()
+    except ThreemaAuthError as err:
+        raise ConfigEntryAuthFailed(
+            translation_domain=DOMAIN,
+            translation_key="invalid_auth",
+        ) from err
+    except ThreemaConnectionError as err:
+        raise ConfigEntryNotReady(
+            translation_domain=DOMAIN,
+            translation_key="cannot_connect",
+        ) from err
+
+    entry.runtime_data = client
+
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ThreemaConfigEntry) -> bool:
+    """Unload a config entry."""
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

homeassistant/components/threema/client.py

@@ -0,0 +1,138 @@
+"""Threema Gateway API client."""
+
+from __future__ import annotations
+
+import logging
+
+from threema.gateway import Connection, GatewayError, key
+from threema.gateway.e2e import TextMessage
+from threema.gateway.exception import GatewayServerError
+from threema.gateway.simple import TextMessage as SimpleTextMessage
+
+from homeassistant.core import HomeAssistant
+
+_LOGGER = logging.getLogger(__name__)
+
+# HTTP 401 from Threema Gateway means invalid credentials
+_HTTP_UNAUTHORIZED = 401
+
+
+class ThreemaConnectionError(Exception):
+    """Error to indicate a connection issue with the Threema Gateway."""
+
+
+class ThreemaAuthError(Exception):
+    """Error to indicate invalid credentials for the Threema Gateway."""
+
+
+class ThreemaSendError(Exception):
+    """Error to indicate a message send failure."""
+
+
+class ThreemaAPIClient:
+    """Threema Gateway API client."""
+
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        gateway_id: str,
+        api_secret: str,
+        private_key: str | None = None,
+    ) -> None:
+        """Initialize the Threema API client."""
+        self.hass = hass
+        self.gateway_id = gateway_id
+        self.api_secret = api_secret
+        self.private_key = private_key
+
+    def _get_connection(self) -> Connection:
+        """Get a Threema Gateway connection.
+
+        Note: Connection manages its own aiohttp session lifecycle.
+        Do not pass HA's shared session as Connection will close it.
+        """
+        return Connection(
+            identity=self.gateway_id,
+            secret=self.api_secret,
+            key=self.private_key,
+        )
+
+    async def validate_credentials(self) -> None:
+        """Validate the Gateway credentials by checking credits.
+
+        Raises ThreemaAuthError for invalid credentials.
+        Raises ThreemaConnectionError for other failures.
+        """
+        try:
+            async with self._get_connection() as conn:
+                remaining_credits = await conn.get_credits()
+                _LOGGER.debug(
+                    "Gateway credentials validated, credits: %s",
+                    remaining_credits,
+                )
+        except GatewayServerError as err:
+            if err.status == _HTTP_UNAUTHORIZED:
+                raise ThreemaAuthError("Invalid Threema Gateway credentials") from err
+            raise ThreemaConnectionError(
+                f"Gateway server error validating credentials: {err}"
+            ) from err
+        except GatewayError as err:
+            raise ThreemaConnectionError(
+                f"Gateway error validating credentials: {err}"
+            ) from err
+        except Exception as err:
+            raise ThreemaConnectionError(
+                f"Failed to validate credentials: {err}"
+            ) from err
+
+    async def send_text_message(self, recipient_id: str, text: str) -> str:
+        """Send a text message to a Threema ID.
+
+        Returns the message ID on success.
+        Raises ThreemaSendError on failure.
+        """
+        try:
+            async with self._get_connection() as conn:
+                if self.private_key:
+                    _LOGGER.debug("Sending E2E encrypted message to %s", recipient_id)
+                    message = TextMessage(
+                        connection=conn,
+                        to_id=recipient_id,
+                        text=text,
+                    )
+                else:
+                    _LOGGER.debug("Sending simple message to %s", recipient_id)
+                    message = SimpleTextMessage(
+                        connection=conn,
+                        to_id=recipient_id,
+                        text=text,
+                    )
+
+                message_id: str = await message.send()
+                _LOGGER.debug("Message sent to %s (ID: %s)", recipient_id, message_id)
+                return message_id
+        except GatewayServerError as err:
+            if err.status == _HTTP_UNAUTHORIZED:
+                raise ThreemaAuthError("Invalid Threema Gateway credentials") from err
+            raise ThreemaSendError(
+                f"Gateway server error sending message to {recipient_id}: {err}"
+            ) from err
+        except GatewayError as err:
+            raise ThreemaSendError(
+                f"Gateway error sending message to {recipient_id}: {err}"
+            ) from err
+        except Exception as err:
+            raise ThreemaSendError(
+                f"Failed to send message to {recipient_id}: {err}"
+            ) from err
+
+
+def generate_key_pair() -> tuple[str, str]:
+    """Generate a new key pair for E2E encryption using official SDK.
+
+    Returns tuple of (private_key, public_key) as encoded strings.
+    """
+    private_key_obj, public_key_obj = key.Key.generate_pair()
+    private_key_str = key.Key.encode(private_key_obj)
+    public_key_str = key.Key.encode(public_key_obj)
+    return private_key_str, public_key_str