benethos-mailbox-common 0.4.0__tar.gz

benethos_mailbox_common-0.4.0/.gitignore

@@ -0,0 +1,62 @@
+# Virtual environment
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Caching / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.cache/
+*.sqlite
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local configuration and secrets
+.env
+# config/: per package, only the templates are versioned
+config/**
+!config/**/
+!config/*/.env.example
+*.token.json
+# containers/*/secrets/: the master key of a deployment, the passwords
+# and the CA of the test mail server
+containers/**/secrets/
+# containers/production/service.env: settings, among them perhaps a secret
+containers/**/service.env
+# containers/production/: the MCP server instances and their routes in Caddy
+containers/production/compose.override.yaml
+containers/production/caddy.d/*.caddy
+
+# Service data: the database holds encrypted credentials, backups the same.
+# data/: per package, only the folders are versioned (.gitkeep)
+data/**
+!data/**/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+**/backups/**
+!**/backups/**/
+
+# Live checks: test server address and test accounts stay local
+live/.env
+
+# .gitkeep holds an empty folder and is kept wherever it is. Only works
+# below folders ignored file by file (as above), not below an ignored folder.
+!.gitkeep

benethos_mailbox_common-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benedikt Oswald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

benethos_mailbox_common-0.4.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: benethos-mailbox-common
+Version: 0.4.0
+Summary: What mailbox-service and mailbox-mcp of Mailbox share: mail as plain text, the folders of the operating system, settings from a file, the time of a log line, secrets masked in text, JSON for a hash.
+Project-URL: Homepage, https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-common#readme
+Project-URL: Repository, https://github.com/benethos-hub/mailbox
+Project-URL: Issues, https://github.com/benethos-hub/mailbox/issues
+Project-URL: Changelog, https://github.com/benethos-hub/mailbox/blob/main/CHANGELOG.md
+Author: Benedikt Oswald
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,html-to-text,logging,redaction,self-hosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: platformdirs>=4.3; extra == 'all'
+Requires-Dist: pydantic-settings>=2.10; extra == 'all'
+Provides-Extra: paths
+Requires-Dist: platformdirs>=4.3; extra == 'paths'
+Provides-Extra: settings
+Requires-Dist: pydantic-settings>=2.10; extra == 'settings'
+Description-Content-Type: text/markdown
+
+# <img src="https://raw.githubusercontent.com/benethos-hub/mailbox/main/assets/logo/icon-3d.svg" alt="" height="36" align="absmiddle"> mailbox-common
+
+[![CI](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml)
+[![PyPI benethos-mailbox-common](https://img.shields.io/pypi/v/benethos-mailbox-common?label=PyPI%20benethos-mailbox-common)](https://pypi.org/project/benethos-mailbox-common/)
+[![Python](https://img.shields.io/pypi/pyversions/benethos-mailbox-common)](https://pypi.org/project/benethos-mailbox-common/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/benethos-hub/mailbox/blob/main/LICENSE)
+
+> **Beta, version 0.4.0.** Usable with real accounts. A breaking change
+> of the API or the configuration is announced in the changelog. Stored
+> data is carried forward by migrations.
+
+What
+[`mailbox-service`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-service)
+and
+[`mailbox-mcp`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-mcp)
+of [Mailbox](https://github.com/benethos-hub/mailbox) both need, held
+once, on PyPI as `benethos-mailbox-common`. The MCP server cannot see
+the service, so what both use lives here.
+
+It is installed with them and is not meant to be used on its own. It
+is built for the packages of this repository, and its modules, groups
+and extras may change between versions without notice. It carries the
+version of the other packages, and the service and the MCP server pin
+it to their own.
+
+Its modules are in five groups, one per concern: `mail` (addresses
+and the plain text of an HTML body), `log` (the log line and the
+masking of secrets), `paths` (the folders of the operating system),
+`settings` (a program's settings from the environment and a file)
+and `values` (secrets, sizes, text and canonical JSON).
+
+It needs the standard library alone. The extra `paths` brings
+platformdirs for the folders of the operating system, `settings`
+pydantic-settings for a program's settings, and `all` brings every
+extra.
+
+It sees neither the service, nor the MCP server, nor the client.

benethos_mailbox_common-0.4.0/README.md

@@ -0,0 +1,37 @@
+# <img src="https://raw.githubusercontent.com/benethos-hub/mailbox/main/assets/logo/icon-3d.svg" alt="" height="36" align="absmiddle"> mailbox-common
+
+[![CI](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml)
+[![PyPI benethos-mailbox-common](https://img.shields.io/pypi/v/benethos-mailbox-common?label=PyPI%20benethos-mailbox-common)](https://pypi.org/project/benethos-mailbox-common/)
+[![Python](https://img.shields.io/pypi/pyversions/benethos-mailbox-common)](https://pypi.org/project/benethos-mailbox-common/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/benethos-hub/mailbox/blob/main/LICENSE)
+
+> **Beta, version 0.4.0.** Usable with real accounts. A breaking change
+> of the API or the configuration is announced in the changelog. Stored
+> data is carried forward by migrations.
+
+What
+[`mailbox-service`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-service)
+and
+[`mailbox-mcp`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-mcp)
+of [Mailbox](https://github.com/benethos-hub/mailbox) both need, held
+once, on PyPI as `benethos-mailbox-common`. The MCP server cannot see
+the service, so what both use lives here.
+
+It is installed with them and is not meant to be used on its own. It
+is built for the packages of this repository, and its modules, groups
+and extras may change between versions without notice. It carries the
+version of the other packages, and the service and the MCP server pin
+it to their own.
+
+Its modules are in five groups, one per concern: `mail` (addresses
+and the plain text of an HTML body), `log` (the log line and the
+masking of secrets), `paths` (the folders of the operating system),
+`settings` (a program's settings from the environment and a file)
+and `values` (secrets, sizes, text and canonical JSON).
+
+It needs the standard library alone. The extra `paths` brings
+platformdirs for the folders of the operating system, `settings`
+pydantic-settings for a program's settings, and `all` brings every
+extra.
+
+It sees neither the service, nor the MCP server, nor the client.

benethos_mailbox_common-0.4.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "benethos-mailbox-common"
+version = "0.4.0"
+description = "What mailbox-service and mailbox-mcp of Mailbox share: mail as plain text, the folders of the operating system, settings from a file, the time of a log line, secrets masked in text, JSON for a hash."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Benedikt Oswald" }]
+keywords = [
+    "email",
+    "html-to-text",
+    "logging",
+    "redaction",
+    "self-hosted",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# It sees neither the service, nor the MCP server, nor the client.
+# The standard library only. A group with a library of its own names it
+# in an extra named after the group.
+dependencies = []
+
+[project.optional-dependencies]
+# The minimum is a version without a known vulnerability: the job
+# lowest-versions of ci.yml checks it against OSV.
+# The folders of the operating system for settings and data
+# (paths/folders.py).
+paths = ["platformdirs>=4.3"]
+# The settings of a program from the environment and a settings file
+# (settings/files.py).
+settings = ["pydantic-settings>=2.10"]
+# Every group.
+all = ["benethos-mailbox-common[paths,settings]"]
+
+[project.urls]
+Homepage = "https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-common#readme"
+Repository = "https://github.com/benethos-hub/mailbox"
+Issues = "https://github.com/benethos-hub/mailbox/issues"
+Changelog = "https://github.com/benethos-hub/mailbox/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/benethos_mailbox_common"]

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/__init__.py

@@ -0,0 +1,17 @@
+"""mailbox-common: what the service and the MCP server of Mailbox both
+need, held once, in groups, one per concern: ``mail``, ``log``, ``paths``
+and ``values``. A module imports only inside its group, so a group can
+be cut out as a package of its own. Callers import a module from its
+group, ``from benethos_mailbox_common.log import lines``, never deeper.
+This file imports no group."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("benethos-mailbox-common")
+except PackageNotFoundError:  # pragma: no cover - running from a bare tree
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/log/__init__.py

@@ -0,0 +1,9 @@
+"""The lines of a log and the secrets kept out of them. Callers import
+the modules from here, ``from benethos_mailbox_common.log import lines,
+redact``."""
+
+from __future__ import annotations
+
+from . import lines, redact
+
+__all__ = ["lines", "redact"]

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/log/lines.py

@@ -0,0 +1,131 @@
+"""The lines of a log, alike in every program of Mailbox (docs/LOGGING.md
+6.9): the time, the level, where a line comes from and the message, a
+noted secret masked (``redact``).
+
+On a terminal a line is short and in colour, elsewhere, in a container
+log or the journal, plain text. What a program logs, and its own kinds
+of lines such as the access line of a web server, stay its own: it
+hands ``Console`` a ``line_of`` for them.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from collections.abc import Callable
+from datetime import datetime
+
+from . import redact
+
+FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+# As uvicorn names them. Its trace level is below debug.
+LEVELS = {
+    "critical": logging.CRITICAL,
+    "error": logging.ERROR,
+    "warning": logging.WARNING,
+    "info": logging.INFO,
+    "debug": logging.DEBUG,
+    "trace": 5,
+}
+
+# ANSI colours, for a terminal only.
+RESET = "\033[0m"
+DIM = "\033[2m"
+_LEVEL_COLOURS = {
+    logging.DEBUG: "\033[34m",
+    logging.INFO: "\033[32m",
+    logging.WARNING: "\033[33m",
+    logging.ERROR: "\033[31m",
+    logging.CRITICAL: "\033[1;31m",
+}
+_SOURCE = "\033[36m"
+# The column of the source: the longest name of an activity of the
+# service, ``activity.<area>.<name>``, has 32 characters (docs/LOGGING.md
+# 7.2).
+SOURCE_WIDTH = 32
+
+# A program's own text for a record, None for the message as it is.
+LineOf = Callable[[logging.LogRecord], str | None]
+
+
+def log_time(value: datetime) -> str:
+    """A time as every line of the log writes it, wherever it stands:
+    ISO 8601, the local time of this machine, to the millisecond, with the
+    offset. ``2026-09-28T10:12:22.123+02:00``."""
+    return value.astimezone().isoformat(timespec="milliseconds")
+
+
+def colours_wanted() -> bool:
+    """Colours on a terminal, unless ``NO_COLOR`` is set (no-color.org)."""
+    return sys.stderr.isatty() and "NO_COLOR" not in os.environ
+
+
+def short_source(name: str, package: str) -> str:
+    """``domain.auth`` for the loggers of ``package``, ``http`` for the
+    access log of uvicorn, ``uvicorn`` for the server."""
+    if name == "uvicorn.access":
+        return "http"
+    if name.startswith("uvicorn"):
+        return "uvicorn"
+    return name.removeprefix(f"{package}.")
+
+
+class Redacting(logging.Formatter):
+    """Each line as written, a noted secret masked: in the message, its
+    arguments and a traceback alike. The time as every line writes it
+    (``log_time``)."""
+
+    def __init__(self, fmt: str = FORMAT) -> None:
+        super().__init__(fmt)
+
+    def format(self, record: logging.LogRecord) -> str:
+        return redact.redact(super().format(record))
+
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        return log_time(datetime.fromtimestamp(record.created).astimezone())
+
+
+class Console(Redacting):
+    """A line for a person at a terminal: the time dim, the level in
+    colour, the source short (``short_source`` of ``package``), and the
+    text ``line_of`` gives, else the message. The time as in every other
+    line."""
+
+    def __init__(self, package: str = "", line_of: LineOf | None = None) -> None:
+        super().__init__()
+        self._package = package
+        self._line_of = line_of
+
+    def format(self, record: logging.LogRecord) -> str:
+        colour = _LEVEL_COLOURS.get(record.levelno, "")
+        source = short_source(record.name, self._package)
+        head = (
+            f"{DIM}{self.formatTime(record)}{RESET} "
+            f"{colour}{record.levelname:<8}{RESET} "
+            f"{_SOURCE}{source:<{SOURCE_WIDTH}}{RESET} "
+        )
+        own = self._line_of(record) if self._line_of is not None else None
+        text = own or record.getMessage()
+        if record.exc_info:
+            text += "\n" + self.formatException(record.exc_info)
+        return redact.redact(head + text)
+
+
+def formatter(
+    package: str, *, colours: bool | None = None, line_of: LineOf | None = None
+) -> logging.Formatter:
+    """``Console`` where ``colours`` is true, by default on a terminal,
+    else the plain ``Redacting``."""
+    if colours is None:
+        colours = colours_wanted()
+    return Console(package, line_of) if colours else Redacting()
+
+
+def stderr_handler(
+    package: str, *, colours: bool | None = None, line_of: LineOf | None = None
+) -> logging.Handler:
+    """A handler that writes to stderr with the ``formatter`` that fits."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter(package, colours=colours, line_of=line_of))
+    return handler

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/log/redact.py

@@ -0,0 +1,48 @@
+"""The secrets a program holds in plain text, kept out of what it writes.
+
+The second line of defence (CONCEPT 7.4): no code logs a secret or puts
+one into an error text on purpose. Whatever still carries one, a
+library's message or a traceback, is written with ``***`` in its place.
+A secret is noted where it is decrypted or received. The newest
+``KEPT`` are held: access tokens come anew every hour, and one in use
+is noted again on its next decryption.
+
+The one module of the package with state of its own: a secret noted
+where it is decrypted must be masked wherever a text is written, in every
+layer and in the log, so the noted secrets are held process-wide.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+
+MASK = "***"
+# Shorter values are not masked: a password "a" would hide every "a".
+SHORTEST = 6
+KEPT = 256
+
+_known: OrderedDict[str, None] = OrderedDict()
+_lock = threading.Lock()
+
+
+def note(secret: str) -> None:
+    """Mask ``secret`` from now on, in every text ``redact`` sees."""
+    if len(secret) < SHORTEST:
+        return
+    with _lock:
+        _known[secret] = None
+        _known.move_to_end(secret)
+        while len(_known) > KEPT:
+            _known.popitem(last=False)
+
+
+def redact(text: str) -> str:
+    """``text`` with every noted secret masked, the longest first, so one
+    secret inside another leaves nothing of the longer behind."""
+    with _lock:
+        known = sorted(_known, key=len, reverse=True)
+    for secret in known:
+        if secret in text:
+            text = text.replace(secret, MASK)
+    return text

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/mail/__init__.py

@@ -0,0 +1,8 @@
+"""Mail itself, nothing of Mailbox. Callers import the modules from here,
+``from benethos_mailbox_common.mail import plaintext``."""
+
+from __future__ import annotations
+
+from . import addresses, plaintext
+
+__all__ = ["addresses", "plaintext"]

benethos_mailbox_common-0.4.0/src/benethos_mailbox_common/mail/addresses.py

@@ -0,0 +1,18 @@
+"""An address as people read it: ``Name <email>``, or the email alone.
+Not the header of a message, which ``email.utils.formataddr`` writes,
+encoding a name beyond ASCII."""
+
+from __future__ import annotations
+
+
+def readable(name: str | None, email: str, *, quoted: bool = False) -> str:
+    """``Name <email>``, the email alone without a name. ``quoted`` puts
+    the name in a quoted string (RFC 5322), with a backslash before a
+    backslash or a double quote in it, so a form reads it back as it was:
+    ``"Smith, Ann" <ann@example.org>``."""
+    if not name:
+        return email
+    if quoted:
+        escaped = name.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}" <{email}>'
+    return f"{name} <{email}>"