mailroom-core 0.1.0__py3-none-any.whl

mailroom_core/__init__.py

@@ -0,0 +1 @@
+"""Mailroom's mail layer, shared by mailroom-mcp and the Mailroom app."""

mailroom_core/config/__init__.py

@@ -0,0 +1,67 @@
+"""Accounts and limits: core's half of the config (`src/config/`), the rest being mailroom-mcp's."""
+
+from mailroom_core.config.errors import (
+    ConfigError,
+    ConfigIssue,
+    config_problem,
+    issues_text,
+    validation_issues,
+)
+from mailroom_core.config.load import (
+    CoreConfig,
+    LoadedCore,
+    loaded_core,
+    sealed_env_secrets,
+    without_secret_envs,
+)
+from mailroom_core.config.schema import (
+    MAX_SAFE_INTEGER,
+    SEND_MODES,
+    AccountAuth,
+    AccountConfig,
+    CoreSettings,
+    Endpoint,
+    EnvName,
+    Identity,
+    Limits,
+    NonEmpty,
+    PasswordAuth,
+    SendMode,
+    Slug,
+    StrictModel,
+    TimeZone,
+    TimeZoneName,
+    core_settings_or_issues,
+    time_zone_name,
+)
+
+__all__ = [
+    "MAX_SAFE_INTEGER",
+    "SEND_MODES",
+    "AccountAuth",
+    "AccountConfig",
+    "ConfigError",
+    "ConfigIssue",
+    "CoreConfig",
+    "CoreSettings",
+    "Endpoint",
+    "EnvName",
+    "Identity",
+    "Limits",
+    "LoadedCore",
+    "NonEmpty",
+    "PasswordAuth",
+    "SendMode",
+    "Slug",
+    "StrictModel",
+    "TimeZone",
+    "TimeZoneName",
+    "config_problem",
+    "core_settings_or_issues",
+    "issues_text",
+    "loaded_core",
+    "sealed_env_secrets",
+    "time_zone_name",
+    "validation_issues",
+    "without_secret_envs",
+]

mailroom_core/config/errors.py

@@ -0,0 +1,100 @@
+"""Config errors, worded as `src/config/load.ts` words them (zod's `prettifyError`)."""
+
+import json
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from pydantic_core import PydanticCustomError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from pydantic import ValidationError
+
+type _IssuePath = tuple[str | int, ...]
+
+
+class ConfigError(Exception):
+    """A config or settings document that cannot be used; the message says why, never a secret."""
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigIssue:
+    """One problem in a document, at a path like `account[0].smtp.tls`."""
+
+    path: _IssuePath
+    message: str
+
+
+def config_problem(message: str) -> PydanticCustomError:
+    """A validation error worded exactly `message` (a ValueError would get a prefix)."""
+    return PydanticCustomError("config", "{message}", {"message": message})
+
+
+def validation_issues(error: ValidationError, prefix: _IssuePath = ()) -> list[ConfigIssue]:
+    """Pydantic's errors as issues, the unknown keys of one table in one issue as zod has them."""
+    details = error.errors(include_url=False, include_input=False)
+    paths = [prefix + tuple(detail["loc"]) for detail in details]
+    found: list[tuple[_IssuePath, str | list[str]]] = []
+    unknown: dict[_IssuePath, list[str]] = {}
+    for detail, path in zip(details, paths, strict=True):
+        if detail["type"] == "too_short":
+            # Pydantic counts the items that passed: an array whose items failed is also short.
+            if any(other[: len(path)] == path and other != path for other in paths):
+                continue
+            minimum = (detail.get("ctx") or {}).get("min_length")
+            found.append((path, f"Too small: expected array to have >={minimum} items"))
+        elif detail["type"] == "string_too_short":
+            minimum = (detail.get("ctx") or {}).get("min_length")
+            found.append((path, f"Too small: expected string to have >={minimum} characters"))
+        elif detail["type"] != "extra_forbidden":
+            found.append((path, _MESSAGES.get(detail["type"], detail["msg"])))
+        elif path[:-1] in unknown:
+            unknown[path[:-1]].append(str(path[-1]))
+        else:
+            unknown[path[:-1]] = [str(path[-1])]
+            found.append((path[:-1], unknown[path[:-1]]))
+    return [
+        ConfigIssue(path, message if isinstance(message, str) else _unrecognized(message))
+        for path, message in found
+    ]
+
+
+def issues_text(issues: Iterable[ConfigIssue]) -> str:
+    """One `✖ message` line per issue, then `  → at path` unless it is about the whole document."""
+    lines: list[str] = []
+    for issue in sorted(issues, key=lambda issue: len(issue.path)):
+        lines.append(f"✖ {issue.message}")
+        if issue.path:
+            lines.append(f"  → at {_dot_path(issue.path)}")
+    return "\n".join(lines)
+
+
+# Pydantic's wording names Python types; the documents are TOML or JSON.
+_MESSAGES = {
+    "tuple_type": "Input should be an array",
+    "model_type": "Input should be an object",
+    "model_attributes_type": "Input should be an object",
+    "dict_type": "Input should be an object",
+}
+
+
+def _unrecognized(keys: list[str]) -> str:
+    quoted = ", ".join(json.dumps(key, ensure_ascii=False) for key in keys)
+    return f"Unrecognized key{'s' if len(keys) > 1 else ''}: {quoted}"
+
+
+_PLAIN_KEY = re.compile(r"[\w$]+", re.ASCII)
+
+
+def _dot_path(path: _IssuePath) -> str:
+    out = ""
+    for segment in path:
+        if isinstance(segment, int):
+            out += f"[{segment}]"
+        elif not _PLAIN_KEY.fullmatch(segment):
+            out += f"[{json.dumps(segment, ensure_ascii=False)}]"
+        else:
+            out += f".{segment}" if out else segment
+    return out

mailroom_core/config/load.py

@@ -0,0 +1,176 @@
+"""Accounts and limits, checked, their secrets opened: core's half of `src/config/load.ts`.
+
+mailroom-mcp adds the bootstrap file and the profiles; `CoreConfig` is the config without them,
+which the send gate takes.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+from mailroom_core.config.errors import ConfigError
+from mailroom_core.config.schema import (
+    AccountConfig,
+    CoreSettings,
+    Limits,
+    TimeZoneName,
+    is_env_name,
+)
+from mailroom_core.crypto import SealedSecretError, SecretsSubkey, open_secret, seal_secret
+
+
+@dataclass(frozen=True, slots=True)
+class CoreConfig:
+    """The running accounts and limits: what the mail layer and the send gate need."""
+
+    time_zone: TimeZoneName
+    """IANA time zone of the dates shown to the model."""
+    limits: Limits
+    accounts: tuple[AccountConfig, ...]
+    secrets: Mapping[str, str] = field(repr=False)
+    """Mailbox password or token per running account id."""
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedCore:
+    config: CoreConfig
+    warnings: tuple[str, ...]
+    """Problems worth logging that do not stop the server."""
+    inactive: tuple[str, ...]
+    """Accounts left out of the config: their stored secret is missing or does not open."""
+
+
+def without_secret_envs(raw: object) -> tuple[object, Mapping[str, str]]:
+    """Take each account's `auth.secret_env` out of raw settings, by account id.
+
+    Settings may name an account's password by environment variable: config.toml's, being
+    imported, or a database's from before 0.2.1. The names come out, for `sealed_env_secrets` to
+    store their values; a malformed one stays where it is, for the schema to refuse.
+    """
+    secret_envs: dict[str, str] = {}
+    if not isinstance(raw, Mapping) or not isinstance(raw.get("account"), list):
+        return raw, MappingProxyType(secret_envs)
+    accounts: list[object] = []
+    for acc in raw["account"]:
+        auth = acc.get("auth") if isinstance(acc, Mapping) else None
+        if not isinstance(auth, Mapping):
+            accounts.append(acc)
+            continue
+        name = auth.get("secret_env")
+        account_id = acc.get("id")
+        if not isinstance(account_id, str) or not is_env_name(name):
+            accounts.append(acc)
+            continue
+        secret_envs[account_id] = name
+        accounts.append({**acc, "auth": {k: v for k, v in auth.items() if k != "secret_env"}})
+    return {**raw, "account": accounts}, MappingProxyType(secret_envs)
+
+
+def sealed_env_secrets(
+    subkey: SecretsSubkey | None, secret_envs: Mapping[str, str], env: Mapping[str, str]
+) -> dict[str, bytes]:
+    """The passwords `secret_envs` names, read from `env` and sealed for the database.
+
+    A missing variable or secrets key is a deployment error: nothing is stored until it is fixed.
+    """
+    sealed: dict[str, bytes] = {}
+    missing: dict[str, None] = {}
+    for account_id, name in secret_envs.items():
+        value = env.get(name, "")
+        if value == "":
+            missing[name] = None
+        elif subkey is not None:
+            sealed[account_id] = seal_secret(subkey, account_id, "password", value)
+    if missing:
+        raise ConfigError(f"missing secrets in the environment: {', '.join(missing)}")
+    if len(sealed) < len(secret_envs):
+        raise ConfigError(
+            f"storing the passwords of {', '.join(secret_envs)} needs [auth] secrets_key_env"
+            " (MAILROOM_SECRETS_KEY)"
+        )
+    return sealed
+
+
+def loaded_core(
+    time_zone: TimeZoneName,
+    settings: CoreSettings,
+    subkey: SecretsSubkey | None,
+    stored: Mapping[str, bytes] = MappingProxyType({}),
+) -> LoadedCore:
+    """The running accounts, each with its secret opened from `stored` (sealed blobs by id).
+
+    An account whose stored secret is missing or does not open (no key, another key) is left out
+    with a warning, so the settings page still comes up to fix it.
+    """
+    secrets: dict[str, str] = {}
+    inactive: list[tuple[str, str]] = []
+    for acc in settings.account:
+        secret = _stored_secret(subkey, acc.id, stored)
+        if isinstance(secret, _Problem):
+            inactive.append((acc.id, secret.reason))
+        else:
+            secrets[acc.id] = secret
+    running = tuple(acc for acc in settings.account if acc.id in secrets)
+    return LoadedCore(
+        config=CoreConfig(
+            time_zone=time_zone,
+            limits=settings.limits,
+            accounts=running,
+            secrets=MappingProxyType(secrets),
+        ),
+        warnings=(
+            *(
+                f'account "{account_id}" is not running: {reason}.'
+                " Enter its password on the settings page."
+                for account_id, reason in inactive
+            ),
+            *_identity_domain_warnings(running),
+            *_auto_approve_warnings(running),
+        ),
+        inactive=tuple(account_id for account_id, _ in inactive),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _Problem:
+    reason: str
+
+
+def _stored_secret(
+    subkey: SecretsSubkey | None, account_id: str, stored: Mapping[str, bytes]
+) -> str | _Problem:
+    """An account's stored secret, or why it cannot be used (never the value)."""
+    blob = stored.get(account_id)
+    if blob is None:
+        return _Problem("it has no stored password")
+    if subkey is None:
+        return _Problem("its stored password needs [auth] secrets_key_env (MAILROOM_SECRETS_KEY)")
+    try:
+        return open_secret(subkey, account_id, "password", blob)
+    except SealedSecretError:
+        return _Problem(
+            "its stored password does not open with this secrets key (another key, or altered)"
+        )
+
+
+def _domain(address: str) -> str:
+    return address[address.rfind("@") + 1 :].lower()
+
+
+def _identity_domain_warnings(accounts: tuple[AccountConfig, ...]) -> list[str]:
+    return [
+        f'account "{acc.id}": identity {identity.address} is outside the login\'s domain;'
+        " the SMTP server may refuse it"
+        for acc in accounts
+        for identity in acc.identities
+        if "@" in acc.login and _domain(identity.address) != _domain(acc.login)
+    ]
+
+
+def _auto_approve_warnings(accounts: tuple[AccountConfig, ...]) -> list[str]:
+    """`auto_approve` only means something in `approval` mode; elsewhere it is likely a mistake."""
+    return [
+        f'account "{acc.id}": auto_approve has no effect with send_mode "{acc.send_mode}"'
+        for acc in accounts
+        if acc.auto_approve and acc.send_mode != "approval"
+    ]

mailroom_core/config/schema.py

@@ -0,0 +1,235 @@
+"""The account and limit settings: core's half of `src/config/schema.ts` (`settingsSchema`).
+
+Profiles, the other half of the settings, and the bootstrap file are mailroom-mcp's. The same
+rules hold for the one-time import from config.toml and for every edit on the settings page.
+"""
+
+import re
+from functools import cache
+from typing import TYPE_CHECKING, Annotated, Final, Literal, NewType, TypeIs, get_args
+from zoneinfo import available_timezones
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    Strict,
+    StrictBool,
+    StrictFloat,
+    StrictInt,
+    StrictStr,
+    ValidationError,
+)
+
+from mailroom_core.config.errors import ConfigError, ConfigIssue, config_problem, validation_issues
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+type SendMode = Literal["off", "drafts", "approval", "direct"]
+SEND_MODES: Final[tuple[SendMode, ...]] = get_args(SendMode.__value__)
+
+MAX_SAFE_INTEGER: Final = 2**53 - 1
+"""The largest integer a JavaScript number holds exactly: the TypeScript server's bound on
+integers and durations, kept so that both accept the same settings."""
+
+TimeZoneName = NewType("TimeZoneName", str)
+"""An IANA time zone known here: made by `time_zone_name` or by a `TimeZone` field only."""
+_TIME_ZONE_PROBLEM = 'must be an IANA time zone, e.g. "Europe/Rome"'
+
+
+@cache
+def _time_zones() -> dict[str, str]:
+    return {zone.lower(): zone for zone in available_timezones()}
+
+
+def _canonical_time_zone(zone: str) -> str | None:
+    """The IANA name `zone` spells in any letter case, as Intl accepts it; None if unknown."""
+    return _time_zones().get(zone.lower()) if zone.isascii() else None
+
+
+def time_zone_name(zone: str) -> TimeZoneName:
+    """`zone` checked as an IANA time zone and given its canonical case; raises `ConfigError`
+    otherwise."""
+    canonical = _canonical_time_zone(zone)
+    if canonical is None:
+        raise ConfigError(f"time zone {zone!r} {_TIME_ZONE_PROBLEM}")
+    return TimeZoneName(canonical)
+
+
+def _check_time_zone(zone: TimeZoneName) -> TimeZoneName:
+    canonical = _canonical_time_zone(zone)
+    if canonical is None:
+        raise config_problem(_TIME_ZONE_PROBLEM)
+    return TimeZoneName(canonical)
+
+
+TimeZone = Annotated[TimeZoneName, Strict(), AfterValidator(_check_time_zone)]
+"""A config field holding an IANA time zone, e.g. `Europe/Rome`."""
+
+_ENV_NAME = re.compile(r"[A-Z_][A-Z0-9_]*")
+_SLUG = re.compile(r"[a-z0-9][a-z0-9-]*")
+# zod's email check, so that both servers accept the same addresses.
+_EMAIL = re.compile(
+    r"(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}"
+)
+_RECIPIENT_RULE = re.compile(r"(?:[^\s@]+@|@)[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+")
+
+
+def _matching(pattern: re.Pattern[str], message: str) -> Callable[[str], str]:
+    def check(text: str) -> str:
+        if pattern.fullmatch(text) is None:
+            raise config_problem(message)
+        return text
+
+    return check
+
+
+def is_env_name(value: object) -> TypeIs[str]:
+    """Whether `value` can name an environment variable: `A-Z`, `0-9` and `_`."""
+    return isinstance(value, str) and _ENV_NAME.fullmatch(value) is not None
+
+
+EnvName = Annotated[
+    StrictStr,
+    AfterValidator(_matching(_ENV_NAME, "must be an environment variable name (A-Z, 0-9, _)")),
+]
+Slug = Annotated[
+    StrictStr,
+    AfterValidator(_matching(_SLUG, "must be lowercase letters, digits and dashes")),
+]
+"""Ids that appear in URLs and tool arguments: `/mcp/<profile>`, `account = "<id>"`."""
+NonEmpty = Annotated[StrictStr, Field(min_length=1)]
+_Email = Annotated[StrictStr, AfterValidator(_matching(_EMAIL, "Invalid email address"))]
+_RecipientRule = Annotated[
+    StrictStr,
+    AfterValidator(
+        _matching(
+            _RECIPIENT_RULE,
+            "must be an address (ana@example.org) or @ plus a domain (@example.org)",
+        )
+    ),
+]
+"""An exact recipient or a whole domain: `ana@example.org`, `@example.org`."""
+_Count = Annotated[StrictInt, Field(ge=1, le=MAX_SAFE_INTEGER)]
+
+
+class StrictModel(BaseModel):
+    """Base of the config models: unknown keys are an error, what is parsed is read-only."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Endpoint(StrictModel):
+    host: NonEmpty
+    port: Annotated[StrictInt, Field(ge=1, le=65_535)]
+    tls: Literal["implicit", "starttls"]
+
+
+class Identity(StrictModel):
+    address: _Email
+    name: NonEmpty | None = None
+    default: StrictBool = False
+
+
+class PasswordAuth(StrictModel):
+    """A password or token, stored sealed in the database.
+
+    config.toml may name it by environment variable instead (`auth.secret_env`):
+    `without_secret_envs` takes that out, and the import seals the variable's value.
+    """
+
+    type: Literal["password"]
+
+
+# A union discriminated on `type` once there is a second kind (0.4: xoauth2).
+type AccountAuth = PasswordAuth
+
+
+class AccountConfig(StrictModel):
+    id: Slug
+    login: NonEmpty
+    send_mode: SendMode
+    auth: AccountAuth
+    imap: Endpoint
+    smtp: Endpoint
+    identities: Annotated[tuple[Identity, ...], Field(min_length=1)]
+    auto_approve: tuple[_RecipientRule, ...] = ()
+    """Recipients (`addr@x` or `@domain`) sent directly in `approval` mode."""
+
+
+class Limits(StrictModel):
+    send_per_hour: _Count = 20
+    max_recipients: _Count = 10
+    body_chars: Annotated[StrictInt, Field(ge=500, le=MAX_SAFE_INTEGER)] = 6000
+    attachment_max_mb: Annotated[StrictFloat, Field(gt=0, allow_inf_nan=False)] = 10.0
+
+
+class CoreSettings(StrictModel):
+    """Accounts and limits, as stored; only `core_settings_or_issues` makes one with its rules."""
+
+    limits: Limits = Limits()
+    account: tuple[AccountConfig, ...] = ()
+
+
+def core_settings_or_issues(raw: object) -> CoreSettings | tuple[ConfigIssue, ...]:
+    """The settings, valid and with a lone identity made the default; else what is wrong."""
+    try:
+        settings = CoreSettings.model_validate({} if raw is None else raw)
+    except ValidationError as error:
+        return tuple(validation_issues(error))
+    issues = _cross_check(settings)
+    if issues:
+        return issues
+    # A single identity is the default one whether or not it says so.
+    return settings.model_copy(
+        update={
+            "account": tuple(
+                acc.model_copy(
+                    update={"identities": (acc.identities[0].model_copy(update={"default": True}),)}
+                )
+                if len(acc.identities) == 1
+                else acc
+                for acc in settings.account
+            )
+        }
+    )
+
+
+def _cross_check(settings: CoreSettings) -> tuple[ConfigIssue, ...]:
+    issues: list[ConfigIssue] = []
+    ids: set[str] = set()
+    logins: set[str] = set()
+    addresses: dict[str, str] = {}
+    for i, acc in enumerate(settings.account):
+        if acc.id in ids:
+            issues.append(ConfigIssue(("account", i, "id"), f'duplicate account id "{acc.id}"'))
+        ids.add(acc.id)
+        # Tools accept a login in any case, so two logins differing only in case would be
+        # ambiguous.
+        login = acc.login.lower()
+        if login in logins:
+            issues.append(ConfigIssue(("account", i, "login"), f'duplicate login "{acc.login}"'))
+        logins.add(login)
+
+        defaults = sum(identity.default for identity in acc.identities)
+        if len(acc.identities) > 1 and defaults != 1:
+            issues.append(
+                ConfigIssue(
+                    ("account", i, "identities"),
+                    f"exactly one identity must be marked default (found {defaults})",
+                )
+            )
+        for j, identity in enumerate(acc.identities):
+            address = identity.address.lower()
+            owner = addresses.get(address)
+            if owner is not None:
+                issues.append(
+                    ConfigIssue(
+                        ("account", i, "identities", j, "address"),
+                        f'identity {address} is already used by account "{owner}"',
+                    )
+                )
+            addresses[address] = acc.id
+    return tuple(issues)

mailroom_core/crypto/__init__.py

@@ -0,0 +1,19 @@
+"""Mailroom's cryptography: mailbox secrets sealed at rest."""
+
+from mailroom_core.crypto.sealed_secrets import (
+    SealedSecretError,
+    SecretPurpose,
+    SecretsSubkey,
+    open_secret,
+    seal_secret,
+    secrets_subkey,
+)
+
+__all__ = [
+    "SealedSecretError",
+    "SecretPurpose",
+    "SecretsSubkey",
+    "open_secret",
+    "seal_secret",
+    "secrets_subkey",
+]

mailroom_core/crypto/sealed_secrets.py

@@ -0,0 +1,65 @@
+"""Mailbox secrets sealed at rest, byte-compatible with `src/crypto/sealed-secrets.ts`.
+
+The format is in docs/DESIGN.md — *Python port*, *Compatibility*.
+"""
+
+from secrets import token_bytes
+from typing import Literal, NewType
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.hashes import SHA256
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+type SecretPurpose = Literal["password"]
+"""What a stored secret is for; the only kind today is a mailbox password or token."""
+
+SecretsSubkey = NewType("SecretsSubkey", bytes)
+"""The key that seals stored secrets. Only `secrets_subkey` makes one: never the raw key."""
+
+_FORMAT = 1
+_NONCE_BYTES = 12
+_TAG_BYTES = 16
+
+
+class SealedSecretError(ValueError):
+    """A blob that does not open: wrong key, altered, moved, or not a stored secret at all."""
+
+
+def secrets_subkey(secrets_key: bytes) -> SecretsSubkey:
+    """Derive the sealing key from MAILROOM_SECRETS_KEY (its 32 bytes, decoded) for this one use."""
+    hkdf = HKDF(algorithm=SHA256(), length=32, salt=None, info=b"mailroom account secrets")
+    return SecretsSubkey(hkdf.derive(secrets_key))
+
+
+def seal_secret(
+    subkey: SecretsSubkey, account_id: str, purpose: SecretPurpose, plaintext: str
+) -> bytes:
+    """AES-256-GCM, as `format ‖ nonce ‖ ciphertext ‖ tag`.
+
+    The account and purpose are bound in as associated data: a blob copied to another account or
+    use does not open.
+    """
+    nonce = token_bytes(_NONCE_BYTES)
+    sealed = AESGCM(subkey).encrypt(
+        nonce, plaintext.encode(), _associated_data(account_id, purpose)
+    )
+    return bytes([_FORMAT]) + nonce + sealed
+
+
+def open_secret(subkey: SecretsSubkey, account_id: str, purpose: SecretPurpose, blob: bytes) -> str:
+    """Raise `SealedSecretError` (without the value) unless the blob opens for this account."""
+    if len(blob) < 1 + _NONCE_BYTES + _TAG_BYTES or blob[0] != _FORMAT:
+        raise SealedSecretError("not a stored secret of a known format")
+    nonce = blob[1 : 1 + _NONCE_BYTES]
+    try:
+        plaintext = AESGCM(subkey).decrypt(
+            nonce, blob[1 + _NONCE_BYTES :], _associated_data(account_id, purpose)
+        )
+    except InvalidTag:
+        raise SealedSecretError("stored secret does not open") from None
+    return plaintext.decode()
+
+
+def _associated_data(account_id: str, purpose: SecretPurpose) -> bytes:
+    return f"mailroom/v1/{account_id}/{purpose}".encode()