terp-cap-mail 0.27.0__tar.gz

terp_cap_mail-0.27.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env
+# Per-service renders (a declaration scoped with "services"). A SEPARATE pattern
+# because `.app.env` above is an exact name, not a glob: it does not match
+# `.app.worker.env`, so without this line the one file that exists to hold a single
+# worker's credentials would be the one file in the seam that gets committed.
+# `.app.env.example` stays tracked -- it does not end in `.env`, so neither line
+# claims it.
+.app.*.env
+# `terp smoke`'s throwaway database. Left in place deliberately after a failure — it is
+# the state the chain died on — so it must not show up as an untracked file.
+.terp-smoke.db
+
+# graphify: a knowledge graph an agent builds FROM this repository. Derived
+# data that is rebuilt on demand and goes stale the moment the code moves.
+graphify-out/
+
+# Playwright browsers recorded to a repo-local path. Needed rather than optional on
+# Windows: the default location under %LOCALAPPDATA% is refused execution by Group
+# Policy on a managed machine ("spawn UNKNOWN" with the binary present and complete),
+# so recording the win32 half of a baseline pair requires PLAYWRIGHT_BROWSERS_PATH
+# pointing somewhere policy allows. 700MB, and nothing in the repo should ever carry it.
+apps/workbench/.playwright-browsers/
+
+# Agent-session git worktrees. Local scratch checkouts of this repository, so a `git add -A`
+# would otherwise stage them as embedded repositories — which it did once, and the commit had
+# to be amended.
+.claude/worktrees/

terp_cap_mail-0.27.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: terp-cap-mail
+Version: 0.27.0
+Summary: Terp mail capability — outbound e-mail through one declared relay: TLS required, a fixed sender, bounded messages, delivered by the jobs seam so a send commits with the write that caused it.
+Project-URL: Repository, https://github.com/AITT-NL/terp-framework
+Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.27.0

terp_cap_mail-0.27.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-no-raw-outbound-http": 1
+}

terp_cap_mail-0.27.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-mail"
+version = "0.27.0"
+description = "Terp mail capability — outbound e-mail through one declared relay: TLS required, a fixed sender, bounded messages, delivered by the jobs seam so a send commits with the write that caused it."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.27.0",
+    # Nothing else, on purpose. The SMTP client is the standard library's `smtplib`,
+    # imported in exactly one module of this distribution -- which is the whole point of
+    # `no_raw_outbound_http` refusing it everywhere else.
+]
+
+# A LIBRARY capability (like terp-cap-egress): no table, no router, and NO `terp.capabilities`
+# auto-discovery entry point. Sending mail is not something an app should acquire by
+# installing a package; it declares a relay with `configure_mail(...)` and registers the
+# `MAIL_SEND` job in its control plane, and both are visible in the composition root.
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.mail`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/mail"]
+
+# Where this package comes from. The shipped changelog (`terp guide changelog`)
+# ends at the installed version; the notes for a release you do not have yet
+# live at these URLs, which `pip show` and the index page both surface.
+[project.urls]
+Repository = "https://github.com/AITT-NL/terp-framework"
+Changelog = "https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md"

terp_cap_mail-0.27.0/src/terp/capabilities/mail/__init__.py

@@ -0,0 +1,67 @@
+"""Terp mail capability — outbound e-mail through one declared relay.
+
+``no_raw_outbound_http`` refuses ``smtplib`` in application code, for the reason it
+refuses a raw HTTP client: whether the connection is encrypted, whether the certificate
+is checked, which account signs in and how long a dead server may hold a worker are
+decisions, and a raw client makes them again at every call site. This capability makes
+them once.
+
+A **library** capability, like ``terp-cap-egress``: no router, no table, no
+auto-discovery entry point. An application declares its relay in the composition root
+and registers the one job; a feature then sends with one call::
+
+    # app/main.py — the relay, from MAIL_FROM / SMTP_HOST / SMTP_PORT / SMTP_SECURITY /
+    # SMTP_USERNAME / SMTP_PASSWORD
+    configure_mail(mail_settings_from_environment(os.environ))
+
+    # control_plane/jobs.py
+    job_catalog = JobCatalog([MAIL_SEND])
+
+    # a module's service, on the session of the write the mail is about
+    send_mail(session, MailMessage(
+        to=[order.customer_email],
+        subject="Your order has shipped",
+        text=f"Order {order.number} is on its way.",
+    ))
+
+``send_mail`` sends nothing itself: it enqueues ``MAIL_SEND`` on the caller's session, so
+with the durable outbox wired the mail commits — or rolls back — with the write, and the
+worker delivers it with retries. The session to the relay is encrypted (STARTTLS or TLS)
+with the certificate verified, credentials never cross an unencrypted connection, the
+sender is fixed, and a message is plain text with one-line headers and a bounded number
+of recipients.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.mail.delivery import (
+    MAIL_SEND,
+    CapturingMailTransport,
+    MailTransport,
+    configure_mail,
+    reset_mail,
+    send_mail,
+)
+from terp.capabilities.mail.errors import MailConfigurationError, MailDeliveryError
+from terp.capabilities.mail.message import MAX_RECIPIENTS, MailMessage
+from terp.capabilities.mail.settings import (
+    MailSecurity,
+    MailSettings,
+    mail_settings_from_environment,
+)
+
+__all__ = [
+    "MAIL_SEND",
+    "MAX_RECIPIENTS",
+    "CapturingMailTransport",
+    "MailConfigurationError",
+    "MailDeliveryError",
+    "MailMessage",
+    "MailSecurity",
+    "MailSettings",
+    "MailTransport",
+    "configure_mail",
+    "mail_settings_from_environment",
+    "reset_mail",
+    "send_mail",
+]

terp_cap_mail-0.27.0/src/terp/capabilities/mail/delivery.py

@@ -0,0 +1,237 @@
+"""``send_mail`` and the ``MAIL_SEND`` job: a send commits with the write that caused it.
+
+A feature sends mail *because* something happened — a work order was closed, an account
+was created — and the send has to agree with the write about whether it happened. Sent
+from the request, it does not: the relay is slow or down and the request fails with it,
+or the mail goes out and the write then rolls back, and a customer is told about a change
+that does not exist. So :func:`send_mail` never talks to a relay. It validates the
+message, mints its ``Message-ID``, and **enqueues** the typed :data:`MAIL_SEND` job on the
+caller's session — which, with the durable outbox wired, is a row committed in the same
+transaction as the business write. The worker (``terp jobs worker``) delivers it
+afterwards, and a delivery that fails raises, so the outbox retries it with backoff and
+dead-letters it once the budget is spent: the one place an operator looks for work that
+did not happen.
+
+With the in-process job queue — the zero-infrastructure default of a development stack —
+the job runs inline, so a failing send fails the request that asked for it. That is the
+loud version of the same failure, in the environment where loud is what you want.
+
+The relay is a process-wide decision made once, in the composition root, by
+:func:`configure_mail` — the API process and the worker both import it, so both hold the
+same one. What it takes is a :class:`~terp.capabilities.mail.MailSettings`, or ``None``
+when the environment names no relay; ``None`` refuses a production boot and, anywhere
+else, installs a stand-in that delivers nothing and says so in the log for every message
+(ADR 0128: permissive in the inner loop, never quiet).
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.headerregistry import Address
+from email.message import EmailMessage
+
+from sqlmodel import Field, Session
+
+from terp.core import (
+    JobContext,
+    JobDefinition,
+    JobVisibility,
+    RetryPolicy,
+    enqueue,
+)
+from terp.core import settings as _platform_settings
+
+from terp.capabilities.mail.errors import MailConfigurationError
+from terp.capabilities.mail.message import MailMessage, build_email
+from terp.capabilities.mail.settings import MailSettings
+from terp.capabilities.mail.smtp import SmtpTransport
+
+_logger = logging.getLogger("terp.capabilities.mail")
+
+#: Where a message goes once it is built: the SMTP relay in a deployment, a
+#: :class:`CapturingMailTransport` in a test. A transport raises to signal a failed
+#: delivery, which is what makes the outbox retry it.
+MailTransport = Callable[[EmailMessage], None]
+
+#: The sender while no relay is configured. ``.invalid`` is reserved (RFC 2606) for names
+#: that must never resolve, which is exactly what an undelivered message should carry.
+_UNCONFIGURED_SENDER = Address(addr_spec="unconfigured@mail.invalid")
+
+
+class CapturingMailTransport:
+    """A transport that keeps every message instead of sending it — for tests.
+
+    ``configure_mail(settings, transport=CapturingMailTransport())`` in a test's setup,
+    and each sent message is an :class:`~email.message.EmailMessage` in :attr:`sent`,
+    rendered exactly as the relay would have received it.
+    """
+
+    def __init__(self) -> None:
+        self.sent: list[EmailMessage] = []
+
+    def __call__(self, message: EmailMessage) -> None:
+        self.sent.append(message)
+
+
+def _log_undelivered(message: EmailMessage) -> None:
+    """The stand-in outside production when no relay is configured: say so, send nothing.
+
+    The subject and the number of recipients reach the log; the addresses and the body
+    do not, because a development database is often a copy of a real one.
+    """
+    _logger.warning(
+        "mail NOT delivered — no relay is configured (set MAIL_FROM and SMTP_HOST): "
+        "%r to %d recipient(s), %s",
+        message["Subject"],
+        len(message["To"].addresses),
+        message["Message-ID"],
+    )
+
+
+@dataclass(frozen=True)
+class _MailRuntime:
+    """What ``configure_mail`` decided: the sender and where a built message goes."""
+
+    sender: Address
+    transport: MailTransport
+
+
+_runtime: _MailRuntime | None = None
+
+
+def configure_mail(
+    settings: MailSettings | None, *, transport: MailTransport | None = None
+) -> None:
+    """Declare this process's relay, once, from the composition root.
+
+    ``settings`` is normally ``mail_settings_from_environment(os.environ)``. ``None`` —
+    the environment names no relay — refuses a **production** boot with
+    :class:`MailConfigurationError` and, anywhere else, installs a stand-in that delivers
+    nothing and logs every message it did not deliver. ``transport`` replaces the SMTP
+    relay — with a test's :class:`CapturingMailTransport`, or with a mail provider's HTTP
+    API built on ``terp.capabilities.egress`` — and is visible here, in the composition
+    root, rather than at any call site. It cannot be combined with ``None``, because a
+    message still needs a sender.
+    """
+    global _runtime
+    if settings is None:
+        if transport is not None:
+            raise ValueError(
+                "configure_mail(None, transport=...) has no sender to build a message "
+                "from; pass the MailSettings the test sends as"
+            )
+        if _platform_settings.is_production:
+            raise MailConfigurationError(
+                "This application sends mail but no relay is configured: set MAIL_FROM "
+                "and SMTP_HOST for this environment."
+            )
+        _logger.warning(
+            "no mail relay is configured: messages are logged, not delivered. A "
+            "production boot is REFUSED in this state."
+        )
+        _runtime = _MailRuntime(_UNCONFIGURED_SENDER, _log_undelivered)
+        return
+    _runtime = _MailRuntime(
+        settings.sender_address,
+        transport if transport is not None else SmtpTransport(settings),
+    )
+
+
+def reset_mail() -> None:
+    """Forget the configured relay (the test-isolation reset)."""
+    global _runtime
+    _runtime = None
+
+
+def _configured() -> _MailRuntime:
+    if _runtime is None:
+        raise MailConfigurationError(
+            "send_mail was called before configure_mail: declare the relay in the "
+            "composition root with configure_mail(mail_settings_from_environment(os.environ))."
+        )
+    return _runtime
+
+
+class MailJobPayload(MailMessage):
+    """The ``MAIL_SEND`` job's payload: the message, plus the identity it was given.
+
+    The ``Message-ID`` rides the payload rather than being minted at delivery, so every
+    retry of one send is the same message to the recipient's mail client.
+    """
+
+    message_id: str = Field(min_length=1, max_length=300)
+
+
+def send_mail(session: Session, message: MailMessage) -> str:
+    """Queue *message* for delivery on *session*, and return its ``Message-ID``.
+
+    Pass the session of the write the mail is about, so the send commits — or rolls back
+    — with it. Nothing is sent from here: the ``MAIL_SEND`` job delivers it. Refused with
+    :class:`MailConfigurationError` when the composition root never called
+    :func:`configure_mail`, so a missing declaration surfaces at the first send rather
+    than as a queue of jobs that can never run.
+    """
+    message_id = f"<{uuid.uuid4().hex}@{_configured().sender.domain}>"
+    enqueue(
+        session,
+        job=MAIL_SEND,
+        payload=MailJobPayload(**message.model_dump(), message_id=message_id),
+        idempotency_key=message_id,
+    )
+    return message_id
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` for the ``Date`` header (private so tests can patch it)."""
+    return datetime.now(UTC)
+
+
+def deliver_mail(ctx: JobContext, payload: MailJobPayload) -> None:
+    """Build the message from the declared sender and hand it to the configured transport.
+
+    ``ctx`` is part of every job handler's contract and unused here: a delivery writes
+    nothing, so it needs neither the session nor the re-bound actor. A failure propagates — :class:`~terp.capabilities.mail.MailDeliveryError` from the
+    relay, or :class:`MailConfigurationError` from a worker that was started without the
+    composition root's ``configure_mail`` — so the outbox retries and, in the end,
+    dead-letters it where an operator will see it.
+    """
+    runtime = _configured()
+    runtime.transport(
+        build_email(
+            payload,
+            sender=runtime.sender,
+            message_id=payload.message_id,
+            sent_at=_utc_now(),
+        )
+    )
+
+
+#: The typed job contract an app registers in its control plane's ``JobCatalog`` — the
+#: capability cannot enqueue a job the catalog does not declare. ``RESTRICTED``, because
+#: the payload holds addresses and a message body. Retries lean on the outbox: a relay
+#: that is down for a while is the common failure, so the backoff starts at a minute,
+#: doubles, and levels off at half an hour before the last attempt dead-letters.
+MAIL_SEND = JobDefinition(
+    name="mail.message.send",
+    payload_schema=MailJobPayload,
+    handler=deliver_mail,
+    retry=RetryPolicy(max_attempts=8, backoff_seconds=60.0, max_backoff_seconds=1800.0),
+    queue="mail",
+    visibility=JobVisibility.RESTRICTED,
+)
+
+
+__all__ = [
+    "MAIL_SEND",
+    "CapturingMailTransport",
+    "MailJobPayload",
+    "MailTransport",
+    "configure_mail",
+    "deliver_mail",
+    "reset_mail",
+    "send_mail",
+]

terp_cap_mail-0.27.0/src/terp/capabilities/mail/errors.py

@@ -0,0 +1,45 @@
+"""The two things that can go wrong on the way to a mail relay, as typed errors.
+
+Both are ``AppError`` subclasses, so a send that fails inline (the in-process job queue,
+in development) reaches a client through the same envelope as every other failure rather
+than as whichever exception ``smtplib`` happened to raise. The distinction between them
+is who has to act: a configuration error is the application's own declaration being
+absent or refused, and a delivery error is the relay.
+"""
+
+from __future__ import annotations
+
+from terp.core import AppError
+
+
+class MailConfigurationError(AppError):
+    """500 — mail is used, but this process has no relay the deployment accepts.
+
+    Raised when :func:`~terp.capabilities.mail.send_mail` is called before the
+    composition root ran :func:`~terp.capabilities.mail.configure_mail`, and by
+    ``configure_mail`` itself when a production process is given no relay at all. A 500
+    rather than a 502: nothing upstream failed — the application was started without a
+    decision it needs.
+    """
+
+    status_code = 500
+    code = "mail_not_configured"
+    default_message = "Sending mail is not configured for this application."
+
+
+class MailDeliveryError(AppError):
+    """502 — the relay could not be reached, refused the session, or refused the message.
+
+    Deliberately not a carrier for the relay's own reply. An SMTP error string routinely
+    names an internal host, an account or a policy; it belongs in the log with the
+    exception chained to it, and what reaches a client is that a mail was not sent.
+    Raised inside the ``MAIL_SEND`` job, it is also the signal that makes the durable
+    outbox retry with backoff and dead-letter once the budget is spent.
+    """
+
+    status_code = 502
+    code = "mail_delivery_failed"
+    default_message = "The mail could not be handed to the mail server."
+
+
+__all__ = ["MailConfigurationError", "MailDeliveryError"]

terp_cap_mail-0.27.0/src/terp/capabilities/mail/message.py

@@ -0,0 +1,140 @@
+"""What one message may carry, validated before it is queued rather than when it is sent.
+
+A mail message is built from data — a customer's address, a work order's title — and the
+two classic ways that goes wrong are both about headers. A line break in a subject or an
+address ends the header and starts a new one, so ``"Hello\\r\\nBcc: everyone@..."`` turns
+a notification into a bulk mail the application never sent on purpose; and an address
+field that accepts ``"a@example.com, b@example.com"`` sends to two people where the code
+meant one. Both are refused here, at the moment a feature *asks* to send, so the refusal
+reaches the code that made the mistake instead of a worker log an hour later.
+
+The message is plain text. That is a decision, not an omission: an HTML body assembled
+from data is a second injection surface — a link or a form placed in a trusted sender's
+mail — and it needs an auto-escaping renderer before it is safe to offer, which this
+capability does not yet have. Everything a notification, a confirmation or a password
+reset needs fits in text.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from email.headerregistry import Address
+from email.message import EmailMessage
+from email.policy import SMTP
+from email.utils import format_datetime
+from typing import Annotated, Final
+
+from pydantic import StringConstraints, field_validator
+from sqlmodel import Field
+
+from terp.core import BaseSchema
+
+from terp.capabilities.mail.settings import breaks_a_header, parse_address
+
+#: At most this many recipients per message. A message to many visible recipients hands
+#: every one of them everybody else's address, and it is the shape relays score as bulk
+#: mail. Sending the same notice to many people is one message per person — one
+#: ``send_mail`` each, which also means one refusal does not sink the rest.
+MAX_RECIPIENTS: Final[int] = 50
+
+#: The subject bound. Long enough for any subject a person reads; short enough that a
+#: feature pasting a whole record into it is refused where it happens.
+MAX_SUBJECT_LENGTH: Final[int] = 250
+
+#: The body bound, in characters. The message travels as a job payload — a row in the
+#: durable outbox — so it is bounded like any other stored input.
+MAX_TEXT_LENGTH: Final[int] = 100_000
+
+
+class MailMessage(BaseSchema):
+    """One message: who it is for, what it says, and where a reply should go.
+
+    There is no ``sender`` field: every message is from the address the application
+    declared in :class:`~terp.capabilities.mail.MailSettings`. ``reply_to`` is where a
+    person's answer lands — the case a per-message sender is usually wanted for, without
+    letting a feature send mail that claims to come from someone else.
+
+    ``text`` is kept exactly as written. The platform trims every other input string,
+    and here that would take the indentation off a first line and the blank lines off
+    the end of a signature — a change to what the author wrote, made in silence.
+    """
+
+    to: list[str] = Field(min_length=1, max_length=MAX_RECIPIENTS)
+    subject: str = Field(min_length=1, max_length=MAX_SUBJECT_LENGTH)
+    text: Annotated[str, StringConstraints(strip_whitespace=False)] = Field(
+        min_length=1, max_length=MAX_TEXT_LENGTH
+    )
+    reply_to: str | None = Field(default=None, max_length=254)
+
+    @field_validator("to")
+    @classmethod
+    def _every_recipient_is_one_address(cls, value: list[str]) -> list[str]:
+        for address in value:
+            parse_address(address)
+        return value
+
+    @field_validator("reply_to")
+    @classmethod
+    def _reply_to_is_one_address(cls, value: str | None) -> str | None:
+        if value is not None:
+            parse_address(value)
+        return value
+
+    @field_validator("subject")
+    @classmethod
+    def _subject_is_one_line(cls, value: str) -> str:
+        if breaks_a_header(value):
+            raise ValueError(
+                "the subject is one line of text: a line break, a line separator or "
+                "another control character in a header starts a header of its own"
+            )
+        return value
+
+    @field_validator("text")
+    @classmethod
+    def _text_says_something(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("the text is empty")
+        # The message is stored as a job payload before it is sent, and PostgreSQL's
+        # JSON types cannot hold a NUL character: accepting one here would turn a
+        # validated send into a database error inside the business write.
+        if "\x00" in value:
+            raise ValueError("the text contains a NUL character")
+        return value
+
+
+def build_email(
+    message: MailMessage,
+    *,
+    sender: Address,
+    message_id: str,
+    sent_at: datetime,
+) -> EmailMessage:
+    """Render *message* as an RFC 5322 message from the declared sender.
+
+    ``Auto-Submitted: auto-generated`` (RFC 3834) is always set: this is mail a program
+    sent, and saying so is what stops an out-of-office reply from starting a loop with
+    it. The ``Message-ID`` is minted when the send was requested and stays the same on
+    every retry, so a message delivered twice after a lost connection is recognisably one
+    message. The body is quoted-printable UTF-8, readable in its raw form.
+    """
+    email = EmailMessage(policy=SMTP)
+    email["From"] = sender
+    email["To"] = [parse_address(address) for address in message.to]
+    if message.reply_to is not None:
+        email["Reply-To"] = parse_address(message.reply_to)
+    email["Subject"] = message.subject
+    email["Date"] = format_datetime(sent_at)
+    email["Message-ID"] = message_id
+    email["Auto-Submitted"] = "auto-generated"
+    email.set_content(message.text, cte="quoted-printable")
+    return email
+
+
+__all__ = [
+    "MAX_RECIPIENTS",
+    "MAX_SUBJECT_LENGTH",
+    "MAX_TEXT_LENGTH",
+    "MailMessage",
+    "build_email",
+]

terp_cap_mail-0.27.0/src/terp/capabilities/mail/settings.py

@@ -0,0 +1,253 @@
+"""The one relay an application sends through, declared once instead of decided per send.
+
+An application that sends mail decides which server it talks to, how the connection is
+protected, which account it signs in as and who the mail is *from*. If any of those is
+an argument to a send, it is decided again at every call site, and the call site is where
+"just this once over plaintext" gets written. So all of them are declaration here, and a
+message carries none of them:
+
+* the **relay** is one host and port, named by configuration and never by a message — a
+  recipient address decides where a mail *ends up*, never which server this process
+  opens a connection to;
+* the connection is **encrypted by default** — STARTTLS on the submission port, or TLS
+  from the first byte on 465 — with the certificate and the hostname verified, and there
+  is no setting that turns the verification off;
+* **credentials travel only over an encrypted connection**, refused at construction
+  otherwise, in every environment;
+* the **sender** is fixed. A message may name a ``Reply-To``, never a ``From``, so a
+  feature cannot be talked into sending mail that claims to come from someone else;
+* a relay without encryption (``MailSecurity.NONE``) exists for the local mail catcher a
+  development stack runs, and a production boot refuses it (ADR 0128's shape: the answer
+  is environment-independent, so a gate can ask it off the production host).
+
+Deliberately absent: the SSRF denylist the egress capability applies. That list exists
+because an outbound URL can be *steered* — built from data a caller influences — and
+this destination cannot: it is the one host the deployment configured. What protects a
+mail relay is that the session is encrypted and the certificate proves the name, which
+is also why a relay on a private network (an on-premises mail server, a development
+catcher on the compose network) needs no exception here.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import unicodedata
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from email.errors import HeaderParseError
+from email.headerregistry import Address
+from enum import StrEnum
+
+from terp.core import settings as _platform_settings
+
+_logger = logging.getLogger("terp.capabilities.mail")
+
+#: A bare hostname: letters, digits and hyphens in dot-separated labels. No scheme, no
+#: port, no path and no user part — each of those is a sign that a URL was pasted where a
+#: host belongs, and a relay "host" of ``smtp://mail.example.com:587`` fails far from here.
+_HOSTNAME = re.compile(r"^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$")
+
+#: ``Display Name <address@example.com>`` — the one shape besides a bare address that a
+#: sender setting takes.
+_NAMED_ADDRESS = re.compile(r"^(?P<name>[^<>]*?)\s*<(?P<address>[^<>]+)>$")
+
+
+class MailSecurity(StrEnum):
+    """How the connection to the relay is protected.
+
+    ``STARTTLS`` upgrades a plain connection before anything else is said — and a relay
+    that does not offer the upgrade is refused rather than spoken to in the clear, which
+    is the downgrade an attacker on the path would otherwise only have to strip one line
+    to cause. ``TLS`` is encrypted from the first byte (port 465). ``NONE`` is the local
+    catcher a development stack runs, and a production boot refuses it.
+    """
+
+    STARTTLS = "starttls"
+    TLS = "tls"
+    NONE = "none"
+
+
+_DEFAULT_PORT: dict[MailSecurity, int] = {
+    MailSecurity.STARTTLS: 587,
+    MailSecurity.TLS: 465,
+    MailSecurity.NONE: 25,
+}
+
+
+def breaks_a_header(value: str) -> bool:
+    """Whether *value* holds a character that ends a header line, or any other control.
+
+    Not only CR and LF. The email package validates and folds a header with
+    ``str.splitlines``, which also breaks at the C1 control U+0085 and the Unicode line
+    and paragraph separators U+2028 and U+2029, so a value checked for CR and LF alone
+    passes validation and is refused when the message is built — a queued mail that can
+    never be sent. The categories below are exactly the ones those breaks fall in (Cc,
+    Zl, Zp), and Cc takes the remaining controls with it.
+    """
+    return any(unicodedata.category(ch) in ("Cc", "Zl", "Zp") for ch in value)
+
+
+def parse_address(value: str) -> Address:
+    """Parse one addr-spec (``someone@example.com``) strictly, or raise ``ValueError``.
+
+    Stricter than what RFC 5322 permits, on purpose: the forms refused here are the ones a
+    feature never means and an attacker sometimes does. A CR or LF anywhere (header
+    injection), a second address smuggled after a comma, an IP-literal domain
+    (``someone@[10.0.0.1]``, which skips the recipient's own mail routing), a domain with no
+    dot, and a non-ASCII local part — which needs an extension (SMTPUTF8) this capability
+    does not negotiate, so accepting it here would only move the refusal to the relay.
+    """
+    if not value or len(value) > 254:
+        raise ValueError(f"not a mail address: {value!r}")
+    try:
+        address = Address(addr_spec=value)
+    except (HeaderParseError, ValueError) as exc:  # the parser's two ways of saying "no"
+        raise ValueError(f"not a mail address: {value!r}") from exc
+    domain = address.domain.lower()
+    if address.addr_spec != value or "." not in domain or not _HOSTNAME.match(domain):
+        raise ValueError(f"not a mail address: {value!r}")
+    return address
+
+
+def parse_sender(value: str) -> Address:
+    """Parse a sender setting: ``someone@example.com`` or ``Name <someone@example.com>``."""
+    named = _NAMED_ADDRESS.match(value.strip())
+    if named is None:
+        return parse_address(value.strip())
+    name = named.group("name").strip().strip('"').strip()
+    if breaks_a_header(name):
+        raise ValueError(f"not a sender: {value!r}")
+    spec = parse_address(named.group("address").strip())
+    return Address(display_name=name, username=spec.username, domain=spec.domain)
+
+
+@dataclass(frozen=True)
+class MailSettings:
+    """The declared relay and sender of one application.
+
+    ``sender`` is the ``From`` of every message — ``someone@example.com`` or
+    ``Name <someone@example.com>``. ``host`` is the relay's bare hostname and ``port``
+    defaults to the conventional one for ``security`` (587, 465, or 25). ``username`` and
+    ``password`` are both set or both empty; ``password`` is kept out of ``repr`` so the
+    object can be logged.
+    """
+
+    sender: str
+    host: str
+    port: int | None = None
+    security: MailSecurity = MailSecurity.STARTTLS
+    username: str = ""
+    password: str = field(default="", repr=False)
+
+    def __post_init__(self) -> None:
+        parse_sender(self.sender)
+        if not _HOSTNAME.match(self.host):
+            raise ValueError(
+                "MailSettings.host is the relay's bare lowercase hostname — no scheme, "
+                f"port or path: {self.host!r}"
+            )
+        if self.port is not None and not 0 < self.port < 65536:
+            raise ValueError(f"MailSettings.port must be a TCP port: {self.port!r}")
+        if bool(self.username) != bool(self.password):
+            raise ValueError(
+                "MailSettings.username and MailSettings.password are set together or not "
+                "at all — a relay account with one half missing fails on the first send"
+            )
+        if self.username and self.security is MailSecurity.NONE:
+            raise ValueError(
+                "MailSettings refuses to sign in to a relay over an unencrypted "
+                "connection: the password would cross the network in the clear. Use "
+                "MailSecurity.STARTTLS or MailSecurity.TLS."
+            )
+
+        # Decided by an environment-INDEPENDENT predicate, so the answer exists somewhere
+        # a gate can read it and not only inside a branch that runs on the production
+        # host. Outside production the same state is said out loud, never tolerated in
+        # silence (ADR 0128).
+        problems = self.production_problems()
+        if problems:
+            if _platform_settings.is_production:
+                raise ValueError("; ".join(problems))
+            _logger.warning(
+                "mail relay %s is configured WITHOUT encryption in this deployment. A "
+                "production boot is REFUSED in this state.",
+                self.host,
+            )
+
+    @property
+    def sender_address(self) -> Address:
+        """The parsed ``From`` address."""
+        return parse_sender(self.sender)
+
+    @property
+    def resolved_port(self) -> int:
+        """The declared port, or the conventional one for the declared security."""
+        return self.port if self.port is not None else _DEFAULT_PORT[self.security]
+
+    def production_problems(self) -> list[str]:
+        """What a production boot refuses about this relay, environment-independent."""
+        if self.security is MailSecurity.NONE:
+            return [
+                f"mail relay {self.host!r} is configured without encryption "
+                "(MailSecurity.NONE); a production relay uses STARTTLS or TLS, because "
+                "every message would otherwise cross the network readable"
+            ]
+        return []
+
+
+def mail_settings_from_environment(
+    environ: Mapping[str, str],
+) -> MailSettings | None:
+    """Read the relay from the fixed environment variables, or ``None`` when none is set.
+
+    The names are fixed — ``MAIL_FROM``, ``SMTP_HOST``, ``SMTP_PORT``, ``SMTP_SECURITY``,
+    ``SMTP_USERNAME`` and ``SMTP_PASSWORD`` — so every Terp application configures its
+    relay the same way, and a deployment tool can name them without reading the code.
+
+    ``MAIL_FROM`` and ``SMTP_HOST`` are the two that decide whether a relay is configured
+    at all, and they are set together: one without the other is a half-finished
+    configuration, and it is refused here rather than discovered at the first send.
+    ``SMTP_SECURITY`` is ``starttls`` (the default), ``tls`` or ``none``. Pass
+    ``os.environ`` from the composition root.
+    """
+    sender = environ.get("MAIL_FROM", "").strip()
+    host = environ.get("SMTP_HOST", "").strip()
+    if not sender and not host:
+        return None
+    if not sender or not host:
+        missing = "MAIL_FROM" if not sender else "SMTP_HOST"
+        raise ValueError(
+            f"{missing} is not set, but the other half of the mail relay is: set "
+            "MAIL_FROM and SMTP_HOST together, or neither"
+        )
+    raw_security = environ.get("SMTP_SECURITY", "").strip().lower() or MailSecurity.STARTTLS
+    try:
+        security = MailSecurity(raw_security)
+    except ValueError as exc:
+        raise ValueError(
+            f"SMTP_SECURITY must be one of starttls, tls or none, not {raw_security!r}"
+        ) from exc
+    raw_port = environ.get("SMTP_PORT", "").strip()
+    try:
+        port = int(raw_port) if raw_port else None
+    except ValueError as exc:
+        raise ValueError(f"SMTP_PORT must be a number, not {raw_port!r}") from exc
+    return MailSettings(
+        sender=sender,
+        host=host.lower(),
+        port=port,
+        security=security,
+        username=environ.get("SMTP_USERNAME", "").strip(),
+        password=environ.get("SMTP_PASSWORD", ""),
+    )
+
+
+__all__ = [
+    "MailSecurity",
+    "breaks_a_header",
+    "MailSettings",
+    "mail_settings_from_environment",
+    "parse_address",
+    "parse_sender",
+]

terp_cap_mail-0.27.0/src/terp/capabilities/mail/smtp.py

@@ -0,0 +1,166 @@
+"""The platform's one SMTP client: the declared relay, encrypted, verified, time-bounded.
+
+``no_raw_outbound_http`` refuses ``smtplib`` in application code and sends the author to
+this capability, for the same arithmetic it applies to HTTP: the things that must be
+right about a connection to a mail server are right in as many places as there are
+clients. Here they are right once:
+
+* **the session is encrypted before anything is said** — STARTTLS, or TLS from the first
+  byte — and a relay that does not offer STARTTLS is refused, never spoken to in the
+  clear, because stripping that one capability line is the whole of a downgrade attack;
+* **the certificate and the hostname are verified**, by the standard library's default
+  context with TLS 1.2 as the floor, and there is no parameter that turns that off;
+* **credentials are sent only inside that session**;
+* **every socket operation is time-bounded**, so a relay that stops answering holds one
+  delivery attempt rather than a worker;
+* the ``EHLO`` greeting names the **sender's domain**, not this machine: the default is
+  the process's own hostname, which inside a container is an internal name the relay
+  would then write into the ``Received`` header of every message.
+
+The relay's own reply is kept out of every error a caller sees. It goes to the log, with
+the exception chained, because a mail server's error text routinely names accounts and
+internal hosts.
+"""
+
+from __future__ import annotations
+
+import logging
+import smtplib  # arch-allow-no-raw-outbound-http: this IS the sanctioned mail seam the rule points every other package at; the relay is the one declared host, encrypted and certificate-verified, and no call site can choose another
+import ssl
+from email.message import EmailMessage
+from typing import Final
+
+from terp.capabilities.mail.errors import MailDeliveryError
+from terp.capabilities.mail.settings import MailSecurity, MailSettings
+
+_logger = logging.getLogger("terp.capabilities.mail")
+
+#: Bounds every socket operation on the relay connection (connect, each command, each
+#: reply). Not a setting: a relay that needs longer than this to answer one command is
+#: not going to deliver the message, and the call site is exactly the place that is
+#: tempted to raise it "just here".
+TIMEOUT_SECONDS: Final[float] = 30.0
+
+#: How much of a relay's error reply reaches the log.
+_REPLY_LOG_LIMIT: Final[int] = 300
+
+
+def _tls_context() -> ssl.SSLContext:
+    """Certificate and hostname verified, TLS 1.2 at least — the only context there is."""
+    context = ssl.create_default_context()
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    return context
+
+
+class SmtpTransport:
+    """Hand one message to the declared relay; raise :class:`MailDeliveryError` if it fails.
+
+    Constructed from :class:`~terp.capabilities.mail.MailSettings` by
+    :func:`~terp.capabilities.mail.configure_mail`; a composition root never builds one
+    itself.
+    """
+
+    def __init__(self, settings: MailSettings) -> None:
+        self._settings = settings
+
+    def _open(self) -> smtplib.SMTP:
+        settings = self._settings
+        greeting = settings.sender_address.domain
+        if settings.security is MailSecurity.TLS:
+            return smtplib.SMTP_SSL(
+                settings.host,
+                settings.resolved_port,
+                local_hostname=greeting,
+                timeout=TIMEOUT_SECONDS,
+                context=_tls_context(),
+            )
+        return smtplib.SMTP(
+            settings.host,
+            settings.resolved_port,
+            local_hostname=greeting,
+            timeout=TIMEOUT_SECONDS,
+        )
+
+    def __call__(self, message: EmailMessage) -> None:
+        settings = self._settings
+        try:
+            client = self._open()
+        except (smtplib.SMTPException, OSError) as exc:
+            raise self._failure(message, exc) from exc
+        try:
+            if settings.security is MailSecurity.STARTTLS:
+                # Raises SMTPNotSupportedError when the relay does not offer the upgrade:
+                # there is no fallback to the unencrypted session.
+                client.starttls(context=_tls_context())
+            if settings.username:
+                client.login(settings.username, settings.password)
+            refused = client.send_message(message)
+        except (smtplib.SMTPException, OSError) as exc:
+            raise self._failure(message, exc) from exc
+        finally:
+            _close(client)
+        recipients = len(message["To"].addresses)
+        if refused:
+            # The relay took the message for some recipients and refused others. That is
+            # not retried: a retry would deliver a second copy to everyone it accepted.
+            _logger.warning(
+                "mail relay %s refused %d of %d recipients of %s",
+                settings.host,
+                len(refused),
+                recipients,
+                message["Message-ID"],
+            )
+        _logger.info(
+            "mail relay %s accepted %s for %d recipient(s)",
+            settings.host,
+            message["Message-ID"],
+            recipients - len(refused),
+        )
+
+    def _failure(self, message: EmailMessage, exc: BaseException) -> MailDeliveryError:
+        """Log what the relay said, and return the error a caller is allowed to see.
+
+        ``OSError`` covers what happens below SMTP: a refused or timed-out connection, a
+        name that does not resolve, a TLS handshake or certificate failure. The relay's
+        reply is logged here, for the operator, because nothing downstream logs it — the
+        durable outbox records only the typed error, and that says nothing on purpose.
+        """
+        settings = self._settings
+        code = getattr(exc, "smtp_code", None)
+        reply = getattr(exc, "smtp_error", b"")
+        if isinstance(reply, bytes):
+            reply = reply.decode("utf-8", "replace")
+        _logger.warning(
+            "mail relay %s:%d did not take %s: %s %s %s",
+            settings.host,
+            settings.resolved_port,
+            message["Message-ID"],
+            type(exc).__name__,
+            code if code is not None else "-",
+            str(reply)[:_REPLY_LOG_LIMIT],
+        )
+        return MailDeliveryError(
+            "The mail could not be handed to the mail server.",
+            log_context={
+                "relay": settings.host,
+                "port": settings.resolved_port,
+                "smtp_code": code,
+                "cause": type(exc).__name__,
+            },
+        )
+
+
+def _close(client: smtplib.SMTP) -> None:
+    """End the session without letting its ending decide the outcome.
+
+    ``QUIT`` comes after the relay has already accepted or refused the message, so an
+    error here says nothing about delivery — and treating it as a failure would make the
+    outbox deliver an accepted message a second time.
+    """
+    try:
+        client.quit()
+    except (smtplib.SMTPException, OSError):
+        client.close()
+
+
+__all__ = ["TIMEOUT_SECONDS", "SmtpTransport"]