bitranox-template-py-cli 2.1.1__tar.gz → 2.1.2__tar.gz

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/CHANGELOG.md

@@ -6,6 +6,22 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [2.1.2] 2026-10-08 09:43:32
+
+### Changed
+- **A refused attachment exits 77, not 1 with a traceback (exit code change).** An attachment
+  btx_lib_mail's security checks refuse (a blocked extension such as `.exe`, a file under a
+  blocked directory, a symlink, a file over the size limit) made `send-email` exit 1 with
+  `Error: Unexpected error - Attachment security violation (...)` and log the refusal with a
+  traceback, as if the program had crashed. Since btx_lib_mail 4.0.0 every blocked extension is
+  refused on every platform, so this is an ordinary outcome on Linux and macOS too. It now exits
+  77 (`ExitCode.ATTACHMENT_REFUSED`, sysexits `EX_NOPERM`: not permitted by policy) with one
+  line, `Error: Attachment refused by security policy - <the library's reason>`, logs no
+  traceback, and delivers nothing. A script that checks for 1 after a refused attachment must
+  check for 77. With `email.attachments.raise_on_security_violation = false` the attachment is
+  still skipped with a warning and the message sent, as before; a violation that names no attachment
+  left to drop is refused in warn mode too, and now exits 77 where it exited 1.
+
 ## [2.1.1] 2026-10-06 18:13:05
 
 ### Fixed

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bitranox_template_py_cli
-Version: 2.1.1
+Version: 2.1.2
 Summary: Template CLI application with configuration management and structured logging
 Project-URL: Homepage, https://github.com/bitranox/bitranox_template_py_cli
 Project-URL: Repository, https://github.com/bitranox/bitranox_template_py_cli.git
@@ -26,7 +26,7 @@ Requires-Dist: click>=8.5.0
 Requires-Dist: lib-cli-exit-tools>=2.4.0
 Requires-Dist: lib-layered-config>=7.0.1
 Requires-Dist: lib-log-rich>=6.3.9
-Requires-Dist: orjson>=3.12.0
+Requires-Dist: orjson>=3.13.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: python-dotenv>=1.2.4
 Requires-Dist: rich-click>=1.9.9

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/docs/systemdesign/module_reference.md

@@ -70,6 +70,7 @@ moves or removes a module, a CLI option or a public name.
 - `tests/conftest.py`  -  Shared fixtures (see Test Fixtures below)
 - `tests/test_behaviors.py`  -  Domain function tests
 - `tests/test_cache_effectiveness.py`  -  Configuration loading returns consistent (cached) results
+- `tests/test_cli_attachment_refused.py`  -  An attachment btx_lib_mail's security checks refuse exits 77 with one `Error:` line, nothing delivered
 - `tests/test_cli_config.py`  -  `config`, `config-deploy`, `config-generate-examples` commands
 - `tests/test_cli_config_errors.py`  -  A configuration that cannot be loaded: who reports it, and who still runs
 - `tests/test_cli_core.py`  -  Traceback, main entry, help, hello, fail, info, unknown command
@@ -136,19 +137,20 @@ Run `lint-imports` to verify compliance.
 
 POSIX-conventional exit codes defined in `adapters/cli/exit_codes.py`:
 
-| Code | Name                | Usage                                                                                                                  |
-|------|---------------------|------------------------------------------------------------------------------------------------------------------------|
-| 0    | `SUCCESS`           | Command completed successfully                                                                                         |
-| 1    | `GENERAL_ERROR`     | Unhandled exception, general failure                                                                                   |
-| 2    | `FILE_NOT_FOUND`    | Attachment or file not found; also click's usage error (bad option value, malformed `--set`, invalid `--profile` name) |
-| 13   | `PERMISSION_DENIED` | Cannot write to target directory                                                                                       |
-| 22   | `INVALID_ARGUMENT`  | Invalid CLI argument or section not found                                                                              |
-| 69   | `SMTP_FAILURE`      | SMTP delivery failed                                                                                                   |
-| 78   | `CONFIG_ERROR`      | Configuration missing, not loadable or invalid                                                                         |
-| 110  | `TIMEOUT`           | Operation timed out                                                                                                    |
-| 130  | `SIGNAL_INT`        | Interrupted (SIGINT/Ctrl+C)                                                                                            |
-| 141  | `BROKEN_PIPE`       | Output pipe closed                                                                                                     |
-| 143  | `SIGNAL_TERM`       | Terminated (SIGTERM)                                                                                                   |
+| Code | Name                 | Usage                                                                                                                  |
+|------|----------------------|------------------------------------------------------------------------------------------------------------------------|
+| 0    | `SUCCESS`            | Command completed successfully                                                                                         |
+| 1    | `GENERAL_ERROR`      | Unhandled exception, general failure                                                                                   |
+| 2    | `FILE_NOT_FOUND`     | Attachment or file not found; also click's usage error (bad option value, malformed `--set`, invalid `--profile` name) |
+| 13   | `PERMISSION_DENIED`  | Cannot write to target directory                                                                                       |
+| 22   | `INVALID_ARGUMENT`   | Invalid CLI argument or section not found                                                                              |
+| 69   | `SMTP_FAILURE`       | SMTP delivery failed                                                                                                   |
+| 77   | `ATTACHMENT_REFUSED` | Attachment refused by btx_lib_mail's security checks (blocked extension or directory, symlink, size, ...)              |
+| 78   | `CONFIG_ERROR`       | Configuration missing, not loadable or invalid                                                                         |
+| 110  | `TIMEOUT`            | Operation timed out                                                                                                    |
+| 130  | `SIGNAL_INT`         | Interrupted (SIGINT/Ctrl+C)                                                                                            |
+| 141  | `BROKEN_PIPE`        | Output pipe closed                                                                                                     |
+| 143  | `SIGNAL_TERM`        | Terminated (SIGTERM)                                                                                                   |
 
 ---
 
@@ -243,7 +245,7 @@ Send email using configured SMTP settings.
 | `--raise-on-missing-attachments / --no-raise-on-missing-attachments` | Override missing-attachment handling |
 | `--raise-on-invalid-recipient / --no-raise-on-invalid-recipient`     | Override invalid-recipient handling  |
 
-**Exit codes:** 0, 2 (file not found, or usage error), 22 (invalid option value), 69 (SMTP failure), 78 (no SMTP hosts, an invalid `[email]` section, or configuration not loadable)
+**Exit codes:** 0, 2 (file not found, or usage error), 22 (invalid option value), 69 (SMTP failure), 77 (an attachment refused by btx_lib_mail's security checks), 78 (no SMTP hosts, an invalid `[email]` section, or configuration not loadable)
 
 ### send-notification
 

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bitranox_template_py_cli"
-version = "2.1.1"
+version = "2.1.2"
 description = "Template CLI application with configuration management and structured logging"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ dependencies = [
     "lib_layered_config>=7.0.1",
     "btx_lib_mail>=4.0.0",
     "pydantic>=2.13.5",
-    "orjson>=3.12.0",
+    "orjson>=3.13.0",
 ]
 license = { text = "MIT" }
 authors = [{ name = "bitranox", email = "bitranox@gmail.com" }]

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/src/bitranox_template_py_cli/__init__conf__.py

@@ -40,7 +40,7 @@ name = "bitranox_template_py_cli"
 #: Human-readable summary shown in CLI help output.
 title = "Template CLI application with configuration management and structured logging"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "2.1.1"
+version = "2.1.2"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/bitranox_template_py_cli"
 #: Author attribution surfaced in CLI output.

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/src/bitranox_template_py_cli/adapters/cli/commands/email/_common.py

@@ -11,6 +11,7 @@ import logging
 import os
 from typing import TYPE_CHECKING, Any, NoReturn, cast
 
+from btx_lib_mail import AttachmentSecurityError
 from pydantic import ValidationError
 
 from bitranox_template_py_cli import __init__conf__
@@ -169,8 +170,10 @@ def execute_with_email_error_handling(
         1. ConfigurationError -> CONFIG_ERROR (78): Missing/invalid config
         2. ValueError -> INVALID_ARGUMENT (22): Invalid parameters or email format
         3. FileNotFoundError -> FILE_NOT_FOUND (2): Missing attachment (if enabled)
-        4. DeliveryError/RuntimeError -> SMTP_FAILURE (69): SMTP transport failures
-        5. Exception (catch-all) -> GENERAL_ERROR (1): Unexpected errors with traceback
+        4. AttachmentSecurityError -> ATTACHMENT_REFUSED (77): An attachment btx_lib_mail's
+           security checks refuse (blocked extension or directory, symlink, size, ...)
+        5. DeliveryError/RuntimeError -> SMTP_FAILURE (69): SMTP transport failures
+        6. Exception (catch-all) -> GENERAL_ERROR (1): Unexpected errors with traceback
 
         This ordering ensures specific exceptions aren't caught by broader handlers.
         When adding new exception types, insert them before the catch-all Exception handler.
@@ -205,6 +208,8 @@ def execute_with_email_error_handling(
             "Attachment file not found",
             exit_code=ExitCode.FILE_NOT_FOUND,
         )
+    except AttachmentSecurityError as exc:
+        _refuse_attachment(exc)
     except (DeliveryError, RuntimeError) as exc:
         _handle_send_error(
             exc,
@@ -264,6 +269,27 @@ def _refuse_email_config(exc: ValidationError, heading: str, *, exit_code: ExitC
     get_current_context().exit(exit_code)
 
 
+def _refuse_attachment(exc: AttachmentSecurityError) -> NoReturn:
+    """Report an attachment btx_lib_mail refused on security grounds, then exit 77.
+
+    The refusal is policy working as configured, not a crash, so no traceback is logged. The
+    user sees the library's reason, which names the violation and the resolved path; it never
+    carries a credential.
+
+    Args:
+        exc: The refusal btx_lib_mail raised.
+
+    Raises:
+        click.exceptions.Exit: Always raised, with the ATTACHMENT_REFUSED exit code.
+    """
+    logger.error(
+        "Attachment refused by security policy",
+        extra={"reason": exc.reason, "violation_type": exc.violation_type.value},
+    )
+    safe_console.echo(f"\nError: Attachment refused by security policy - {exc.reason}", err=True)
+    get_current_context().exit(ExitCode.ATTACHMENT_REFUSED)
+
+
 def _handle_send_result(result: bool, recipients: list[str] | None, message_type: str) -> None:
     """Handle the result of a send operation.
 

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/src/bitranox_template_py_cli/adapters/cli/exit_codes.py

@@ -27,6 +27,8 @@ class ExitCode(IntEnum):
     * 2-13: errno-derived codes (ENOENT, EACCES)
     * 22: EINVAL
     * 69: EX_UNAVAILABLE (sysexits.h)
+    * 77: EX_NOPERM (sysexits.h): refused by policy, such as an email attachment
+      btx_lib_mail's security checks reject
     * 78: EX_CONFIG (sysexits.h)
     * 110: ETIMEDOUT
     * 128+N: signal N (informational only)
@@ -44,6 +46,7 @@ class ExitCode(IntEnum):
     PERMISSION_DENIED = 13
     INVALID_ARGUMENT = 22
     SMTP_FAILURE = 69
+    ATTACHMENT_REFUSED = 77
     CONFIG_ERROR = 78
     TIMEOUT = 110
     SIGNAL_INT = 130

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/src/bitranox_template_py_cli/adapters/config/defaultconfig.d/50-mail.toml

@@ -235,5 +235,6 @@ allow_symlinks = false
 # Default: true (raise AttachmentSecurityError)
 # Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__ATTACHMENTS__RAISE_ON_SECURITY_VIOLATION=true
 # .env: EMAIL__ATTACHMENTS__RAISE_ON_SECURITY_VIOLATION=true
-# Note: When false, violations log a warning and skip the attachment
+# Note: When true, send-email refuses the whole message and exits 77 (EX_NOPERM)
+#   naming the violation; when false, violations log a warning and skip the attachment
 raise_on_security_violation = true

{bitranox_template_py_cli-2.1.1 → bitranox_template_py_cli-2.1.2}/src/bitranox_template_py_cli/adapters/email/transport.py

@@ -128,6 +128,10 @@ def send_email(
         ConfigurationError: No SMTP hosts configured.
         FileNotFoundError: Required attachment missing or unreadable and
             config.raise_on_missing_attachments is True.
+        AttachmentSecurityError: btx_lib_mail's security checks refused an
+            attachment (blocked extension or directory, symlink, size, ...)
+            and config.attachment_raise_on_security_violation is True.
+            Raised before anything is delivered.
         DeliveryError: All SMTP hosts failed for a recipient.
 
     Side Effects:

bitranox_template_py_cli-2.1.2/tests/test_cli_attachment_refused.py

@@ -0,0 +1,191 @@
+"""An attachment btx_lib_mail refuses on security grounds exits 77, through the real ``main()``.
+
+The refusal is btx_lib_mail's own check, run by the real ``send_email`` adapter: only the SMTP
+transport is replaced, by a recorder, so a test proves both the exit code and that nothing was
+delivered. ``AttachmentSecurityError`` is neither a ``ValueError`` nor a ``RuntimeError``, so
+without its own branch it fell into the catch-all as exit 1, "Unexpected error".
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import shutil
+import tempfile
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any
+
+import pytest
+from btx_lib_mail import ConfMail
+from lib_layered_config import Config
+
+from bitranox_template_py_cli.adapters.cli.exit_codes import ExitCode
+from bitranox_template_py_cli.adapters.cli.main import main
+from bitranox_template_py_cli.adapters.email.transport import send_email
+from bitranox_template_py_cli.composition import AppServices, build_testing
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+
+    from btx_lib_mail.lib_mail import DeliveryOptions
+
+    from bitranox_template_py_cli.adapters.email.config import EmailConfig
+
+EMAIL = {"email": {"smtp_hosts": ["smtp.test.com:587"], "from_address": "sender@test.com"}}
+SEND_EMAIL = ["send-email", "--to", "recipient@test.com", "--subject", "s", "--body", "b"]
+REFUSED = "Error: Attachment refused by security policy - "
+
+
+class _Recording:
+    """A transport that records each recipient it is handed and sends nothing."""
+
+    def __init__(self) -> None:
+        self.recipients: list[str] = []
+
+    def deliver(self, *, host: str, sender: str, recipient: str, message: IO[bytes], delivery: DeliveryOptions) -> None:
+        self.recipients.append(recipient)
+
+
+def _real_send_email(transport: _Recording) -> Callable[..., bool]:
+    """The production ``send_email`` adapter with only its SMTP transport replaced."""
+
+    def send(
+        *,
+        config: EmailConfig,
+        recipients: str | Sequence[str] | None = None,
+        subject: str,
+        body: str = "",
+        body_html: str = "",
+        from_address: str | None = None,
+        attachments: Sequence[Path] | None = None,
+    ) -> bool:
+        return send_email(
+            config=config,
+            recipients=recipients,
+            subject=subject,
+            body=body,
+            body_html=body_html,
+            from_address=from_address,
+            attachments=attachments,
+            transport=transport,
+        )
+
+    return send
+
+
+def _services(transport: _Recording, data: dict[str, Any]) -> Callable[[], AppServices]:
+    config = Config(data, {})
+
+    def get_config(**_kwargs: Any) -> Config:
+        return config
+
+    def build() -> AppServices:
+        return dataclasses.replace(build_testing(), get_config=get_config, send_email=_real_send_email(transport))
+
+    return build
+
+
+def _send_with(attachment: Path, transport: _Recording, data: dict[str, Any] = EMAIL) -> int:
+    return main([*SEND_EMAIL, "--attachment", str(attachment)], services_factory=_services(transport, data))
+
+
+def _error_lines(err: str) -> list[str]:
+    return [line for line in err.splitlines() if line.startswith("Error:")]
+
+
+def _is_blocked(directory: Path) -> bool:
+    resolved = directory.resolve()
+    return any(resolved.is_relative_to(blocked.resolve()) for blocked in ConfMail().attachment_blocked_directories)
+
+
+def _a_file_in_a_blocked_directory() -> Path:
+    for directory in sorted(ConfMail().attachment_blocked_directories):
+        if not directory.is_dir():
+            continue
+        for entry in sorted(directory.iterdir()):
+            if entry.is_file() and not entry.is_symlink():
+                return entry
+    raise AssertionError("no regular file directly inside any default blocked directory on this OS")
+
+
+@pytest.fixture
+def unblocked_dir(tmp_path: Path) -> Iterator[Path]:
+    """A fresh directory under no default blocked directory, so only the file itself is judged.
+
+    pytest's tmp_path is under /var on macOS (/private/var/folders), which the defaults block.
+    """
+    base = next((base for base in (tmp_path, Path.home(), Path.cwd()) if not _is_blocked(base)), None)
+    assert base is not None, "no candidate directory is outside the default blocked directories"
+    directory = Path(tempfile.mkdtemp(prefix="attachment-refused-", dir=base))
+    yield directory
+    shutil.rmtree(directory, ignore_errors=True)
+
+
+@pytest.mark.os_agnostic
+def test_the_attachment_refused_code_is_sysexits_ex_noperm() -> None:
+    assert ExitCode.ATTACHMENT_REFUSED == 77
+
+
+@pytest.mark.os_agnostic
+def test_a_blocked_extension_exits_77_with_one_error_line_and_delivers_nothing(
+    capsys: pytest.CaptureFixture[str], caplog: pytest.LogCaptureFixture, unblocked_dir: Path
+) -> None:
+    attachment = unblocked_dir / "x.exe"
+    attachment.write_bytes(b"MZ")
+    transport = _Recording()
+
+    exit_code = _send_with(attachment, transport)
+
+    err = capsys.readouterr().err
+    assert exit_code == 77
+    assert _error_lines(err) == [f'{REFUSED}extension ".exe" is blocked: "{attachment.resolve()}"']
+    assert "Unexpected error" not in err
+    assert [record.getMessage() for record in caplog.records if record.exc_info] == []
+    assert transport.recipients == []
+
+
+@pytest.mark.os_agnostic
+def test_a_file_in_a_blocked_directory_exits_77_with_one_error_line_and_delivers_nothing(
+    capsys: pytest.CaptureFixture[str], caplog: pytest.LogCaptureFixture
+) -> None:
+    attachment = _a_file_in_a_blocked_directory()
+    transport = _Recording()
+
+    exit_code = _send_with(attachment, transport)
+
+    err = capsys.readouterr().err
+    lines = _error_lines(err)
+    assert exit_code == 77
+    assert len(lines) == 1
+    assert lines[0].startswith(f"{REFUSED}path under blocked directory ")
+    assert "Unexpected error" not in err
+    assert [record.getMessage() for record in caplog.records if record.exc_info] == []
+    assert transport.recipients == []
+
+
+@pytest.mark.os_agnostic
+def test_an_ordinary_attachment_is_delivered(capsys: pytest.CaptureFixture[str], unblocked_dir: Path) -> None:
+    """The control: the same wiring delivers a harmless file, so the 77 above is the refusal."""
+    attachment = unblocked_dir / "report.txt"
+    attachment.write_text("ok", encoding="utf-8")
+    transport = _Recording()
+
+    exit_code = _send_with(attachment, transport)
+
+    assert exit_code == 0, capsys.readouterr().err
+    assert transport.recipients == ["recipient@test.com"]
+
+
+@pytest.mark.os_agnostic
+def test_with_security_violations_set_to_warn_the_blocked_file_is_skipped_and_the_message_sent(
+    capsys: pytest.CaptureFixture[str], unblocked_dir: Path
+) -> None:
+    """77 belongs to the strict setting: in warn mode btx_lib_mail drops the file and sends the rest."""
+    attachment = unblocked_dir / "x.exe"
+    attachment.write_bytes(b"MZ")
+    transport = _Recording()
+    warn = {"email": {**EMAIL["email"], "attachments": {"raise_on_security_violation": False}}}
+
+    exit_code = _send_with(attachment, transport, warn)
+
+    assert exit_code == 0, capsys.readouterr().err
+    assert transport.recipients == ["recipient@test.com"]