tina4-python 3.13.91__tar.gz → 3.13.94__tar.gz

{tina4_python-3.13.91 → tina4_python-3.13.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.91
+Version: 3.13.94
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -742,7 +742,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 97 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 98 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.91 → tina4_python-3.13.94}/README.md

@@ -710,7 +710,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 97 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 98 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.91 → tina4_python-3.13.94}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.91"
+version = "3.13.94"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/CLAUDE.md

@@ -794,11 +794,18 @@ db.insert("users", {"name": "Alice", "email": "alice@example.com"})
 # Insert multiple
 db.insert("users", [{"name": "Bob"}, {"name": "Eve"}])
 
-# Update (by primary key — default "id")
+# Update (the primary key in the data IS the filter — introspected, not assumed)
 db.update("users", {"id": 1, "name": "Alice Updated"})
 
-# Delete
+# Update many rows — the filter must be explicit
+db.update("users", {"active": 0}, "last_login < ?", ["2025-01-01"])
+
+# Delete (dict filter or string + params, both accepted)
 db.delete("users", {"id": 1})
+db.delete("users", "age < ?", [18])
+
+# Empty a table — explicit, never accidental
+db.truncate("users")
 
 # Raw query
 result = db.fetch("SELECT * FROM users WHERE age > ?", [18])

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/__init__.py

@@ -43,7 +43,15 @@ def _resolve_version() -> str:
             pass
     except Exception:
         pass
-    return "3.13.56"
+    # Floor literal, reached only when BOTH lookups above miss. That is not
+    # theoretical: the Docker build used to prune dist-info from the installed
+    # package, so path 2 raised PackageNotFoundError and the published
+    # tina4-python:3.13.94 image served this literal on /health -- then reading
+    # "3.13.56", 36 releases stale, because nothing kept it current.
+    #
+    # test_version_constant.py now asserts this literal equals the pyproject
+    # version, so the release bump cannot leave it behind again.
+    return "3.13.94"
 
 
 __version__ = _resolve_version()

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/auth/__init__.py

@@ -196,19 +196,51 @@ def _resolve_secret(secret: str = None) -> str:
     return env_secret
 
 
+# Supported JWT algorithms. HMAC only — the whole family is in hashlib, so this
+# stays zero-dependency. The header's "alg" is now always the one we actually sign
+# with (python#105): the digest is looked up here rather than hardcoded.
+_HMAC_ALGORITHMS = {
+    "HS256": hashlib.sha256,
+    "HS384": hashlib.sha384,
+    "HS512": hashlib.sha512,
+}
+
+# Seconds of clock skew tolerated on the "nbf" (not-before) claim. Without this a
+# token minted on one host and validated on another a second behind is rejected
+# for no real reason; RFC 7519 explicitly allows "a small leeway".
+_JWT_LEEWAY_SECONDS = 60
+
+
+def _resolve_algorithm(algorithm: str = None) -> str:
+    """Pick the JWT algorithm: explicit arg, else TINA4_JWT_ALGORITHM, else HS256.
+
+    Raises ValueError naming the supported set when asked for one we cannot sign
+    (python#106 — the env var was registered in the CLI's known_vars and then
+    silently ignored, so a user could set HS512 and still get HS256 tokens).
+    """
+    chosen = (algorithm or os.environ.get("TINA4_JWT_ALGORITHM") or "HS256").strip()
+    if chosen not in _HMAC_ALGORITHMS:
+        raise ValueError(
+            f"Unsupported JWT algorithm {chosen!r}. Tina4 signs with "
+            f"{', '.join(sorted(_HMAC_ALGORITHMS))} (HMAC only, zero-dependency). "
+            f"Set TINA4_JWT_ALGORITHM to one of those."
+        )
+    return chosen
+
+
 class Auth:
     """JWT authentication and password hashing — zero dependencies."""
 
-    def __init__(self, secret: str = None, algorithm: str = "HS256",
+    def __init__(self, secret: str = None, algorithm: str = None,
                  expires_in: int = None):
         """
         Args:
             secret:     Signing secret (falls back to the TINA4_SECRET env var).
-            algorithm:  JWT algorithm (default HS256).
+            algorithm:  JWT algorithm (falls back to TINA4_JWT_ALGORITHM, then HS256).
             expires_in: Token lifetime in seconds (default 3600).
         """
         self.secret = secret if secret is not None else _resolve_secret()
-        self.algorithm = algorithm
+        self.algorithm = _resolve_algorithm(algorithm)
         # JWT expiry env var:
         # - TINA4_TOKEN_EXPIRES_IN (preferred — matches docs and the
         #   form-token expiry env var used by Frond)
@@ -275,13 +307,29 @@ class Auth:
                 return None
 
             h, p, sig = parts
+
+            # Pin the algorithm to OUR configured one instead of trusting the
+            # token's header. A token asking to be verified as anything else --
+            # "none", a weaker HMAC, or an RSA alg we do not implement -- is
+            # rejected before any signature work. Matches the Ruby check.
+            header = json.loads(_b64url_decode(h))
+            if header.get("alg") != self.algorithm:
+                return None
+
             expected = self._sign(f"{h}.{p}")
             if not hmac.compare_digest(sig, expected):
                 return None
 
             payload = json.loads(_b64url_decode(p))
 
-            if "exp" in payload and time.time() > payload["exp"]:
+            now = time.time()
+            if "exp" in payload and now > payload["exp"]:
+                return None
+
+            # "nbf" (not-before): a post-dated token is not valid yet. Was
+            # honoured only by Ruby, so Python/PHP/Node accepted tokens their
+            # issuer had explicitly marked as not-yet-usable (python#107).
+            if "nbf" in payload and now + _JWT_LEEWAY_SECONDS < payload["nbf"]:
                 return None
 
             return payload
@@ -314,8 +362,10 @@ class Auth:
         return self.get_token(payload, expires_in=expires_in)
 
     def _sign(self, message: str) -> str:
+        # Digest comes from the configured algorithm, so the "alg" we advertise in
+        # the header is the one that actually produced this signature.
         sig = hmac.new(
-            self.secret.encode(), message.encode(), hashlib.sha256
+            self.secret.encode(), message.encode(), _HMAC_ALGORITHMS[self.algorithm]
         ).digest()
         return _b64url_encode(sig)
 
@@ -424,16 +474,24 @@ class Auth:
     # ── Request Auth Helper ───────────────────────────────────────
 
     @_DualMethod
-    def authenticate_request(self, headers: dict, secret: str = None, algorithm: str = "HS256") -> dict | None:
+    def authenticate_request(self, headers: dict, secret: str = None, algorithm: str = None) -> dict | None:
         """Extract and validate auth from request headers.
 
         Args:
             secret:    Override signing secret (default: self.secret / TINA4_SECRET env var).
-            algorithm: JWT algorithm override (default: "HS256").
+            algorithm: JWT algorithm override (default: self.algorithm / TINA4_JWT_ALGORITHM).
 
         Checks: Bearer JWT, Bearer API key, Basic auth.
         Returns payload dict on success, None on failure.
         """
+        # Both overrides used to be accepted and then dropped on the floor: the
+        # body called self.valid_token(), so a caller passing secret= or
+        # algorithm= silently got this instance's values instead. Honour them.
+        if secret is not None or algorithm is not None:
+            return Auth(secret=secret if secret is not None else self.secret,
+                        algorithm=algorithm or self.algorithm,
+                        expires_in=self.expires_in).authenticate_request(headers)
+
         auth_header = headers.get("authorization", "")
 
         if auth_header.startswith("Bearer "):
@@ -497,10 +555,10 @@ def refresh_token(token: str, expires_in: int = 60) -> str | None:
     return Auth.refresh_token_static(token, expires_in=expires_in)
 
 
-def authenticate_request(headers: dict, secret: str = None, algorithm: str = "HS256") -> dict | None:
+def authenticate_request(headers: dict, secret: str = None, algorithm: str = None) -> dict | None:
     """Validate auth from request headers — reads TINA4_SECRET from env."""
-    if secret is not None:
-        return Auth(secret=secret).authenticate_request(headers, algorithm=algorithm)
+    if secret is not None or algorithm is not None:
+        return Auth(secret=secret, algorithm=algorithm).authenticate_request(headers)
     return Auth.authenticate_request_static(headers)
 
 

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/database/connection.py

@@ -188,6 +188,7 @@ class Database:
         self._connect_kwargs = kwargs  # Extra kwargs passed through to adapter.connect()
         self.last_error = None  # Last execute() error message
         self._last_id = None   # Last insert ID from execute/insert
+        self._pk_cache = {}    # table -> primary-key column name (or None)
 
         if self.pool_size > 0:
             # Pooled mode — create a ConnectionPool with lazy adapter creation
@@ -681,19 +682,123 @@ class Database:
             self._last_id = result.last_id
         return result
 
+    def primary_key(self, table: str) -> list[str]:
+        """The table's primary-key columns, introspected once and cached.
+
+        Returns a LIST because a primary key may span several columns. A
+        composite key is still one primary key; it just has more than one
+        column. Returns ``[]`` when the table has no primary key or cannot be
+        introspected.
+
+        Uses the cross-engine ``get_columns()`` contract (v3.13.14, #48), which
+        reports ``primary_key`` per column on every adapter.
+        """
+        if table not in self._pk_cache:
+            try:
+                columns = self._get_adapter().get_columns(table)
+                self._pk_cache[table] = [
+                    c["name"] for c in columns if c.get("primary_key")
+                ]
+            except Exception:  # noqa: BLE001 - a missing table is not an error here
+                self._pk_cache[table] = []
+        return self._pk_cache[table]
+
+    def _as_where(self, filter_sql, params):
+        """Normalise a filter to ``(sql, params)``, accepting a dict or a string.
+
+        The declared type on ``delete`` has always been ``str | dict | list``, but
+        only the base adapter honoured the dict and every engine overrides it, so a
+        dict landed in the SQL string verbatim. Normalising here makes the declared
+        type true for every engine at once.
+        """
+        if isinstance(filter_sql, dict):
+            if not filter_sql:
+                return "", []
+            where = " AND ".join(
+                f"{self.quote_identifier(k)} = ?" for k in filter_sql
+            )
+            return where, list(filter_sql.values())
+        return filter_sql, params or []
+
     def update(self, table: str, data: dict,
-               filter_sql: str = "", params: list = None) -> DatabaseResult:
+               filter_sql: str | dict = "", params: list = None) -> DatabaseResult:
+        """Update rows. A write with no filter is an error, not a full-table write.
+
+        With no explicit filter, the primary key is taken out of ``data`` and used
+        as the WHERE clause. With neither a filter nor a primary key in ``data``,
+        this raises rather than overwriting every row (audit feature 4, P1).
+        """
+        filter_sql, params = self._as_where(filter_sql, params)
+
+        if not filter_sql:
+            pk_columns = self.primary_key(table)
+            missing = [c for c in pk_columns if c not in data]
+            if not pk_columns or missing:
+                raise ValueError(
+                    f"update requires a filter or the complete primary key in the "
+                    f"data; pass filter explicitly to update multiple rows "
+                    f"(table={table!r}, primary key={pk_columns!r}, "
+                    f"missing from data={missing!r}). "
+                    f"To empty a table use truncate({table!r})."
+                )
+            # Every primary-key column becomes part of the WHERE clause. A
+            # composite key that used only its first column would match every
+            # row sharing that value - the data-loss bug this method exists to
+            # prevent, reintroduced.
+            data = dict(data)
+            params = [data.pop(c) for c in pk_columns]
+            if not data:
+                raise ValueError(
+                    f"update was given only the primary key {pk_columns!r} and no "
+                    f"columns to set (table={table!r})"
+                )
+            filter_sql = " AND ".join(
+                f"{self.quote_identifier(c)} = ?" for c in pk_columns
+            )
+
         if self._cache_enabled:
             self._cache_invalidate()
-        adapter = self._get_adapter()
-        return adapter.update(table, data, filter_sql, params)
+        result = self._get_adapter().update(table, data, filter_sql, params)
+        return self._without_last_id(result)
 
     def delete(self, table: str,
                filter_sql: str | dict | list = "", params: list = None) -> DatabaseResult:
+        """Delete rows. A filterless delete raises; use ``truncate()`` to empty."""
+        if isinstance(filter_sql, list):
+            total = 0
+            for row_filter in filter_sql:
+                total += self.delete(table, row_filter).affected_rows
+            return DatabaseResult(affected_rows=total)
+
+        filter_sql, params = self._as_where(filter_sql, params)
+        if not filter_sql:
+            raise ValueError(
+                f"delete requires a filter (table={table!r}). "
+                f"To remove every row use truncate({table!r})."
+            )
+
         if self._cache_enabled:
             self._cache_invalidate()
-        adapter = self._get_adapter()
-        return adapter.delete(table, filter_sql, params)
+        result = self._get_adapter().delete(table, filter_sql, params)
+        return self._without_last_id(result)
+
+    def truncate(self, table: str) -> DatabaseResult:
+        """Remove every row. The explicit spelling of a whole-table delete."""
+        if self._cache_enabled:
+            self._cache_invalidate()
+        result = self._get_adapter().delete(table, "1 = 1", [])
+        return self._without_last_id(result)
+
+    @staticmethod
+    def _without_last_id(result: DatabaseResult) -> DatabaseResult:
+        """``last_id`` is insert-only, per the documented contract.
+
+        PHP already does this via ``writeResult($adapter, withLastId: false)``;
+        Python reported the connection's last insert id on an UPDATE.
+        """
+        if result is not None and getattr(result, "last_id", None) is not None:
+            result.last_id = None
+        return result
 
     def start_transaction(self):
         """Begin a transaction. Pins the adapter to this thread for the

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/frond/engine.py

@@ -1626,11 +1626,57 @@ class Frond:
             )
         """
         self._sandbox = True
-        self._allowed_filters = set(allowed_filters) if allowed_filters else None
-        self._allowed_tags = set(allowed_tags) if allowed_tags else None
-        self._allowed_vars = set(allowed_vars) if allowed_vars else None
+        # `is not None`, NOT truthiness: an EMPTY list means "permit nothing",
+        # while None means "permit everything". Testing truthiness collapsed the
+        # two, so a caller that computed an allow-list and got an empty result
+        # silently opened the sandbox instead of closing it.
+        self._allowed_filters = set(allowed_filters) if allowed_filters is not None else None
+        self._allowed_tags = set(allowed_tags) if allowed_tags is not None else None
+        self._allowed_vars = set(allowed_vars) if allowed_vars is not None else None
         return self
 
+    def _filter_permitted(self, fname: str) -> bool:
+        """Is this filter permitted to run under the current sandbox?
+
+        The single source of truth for "may this filter run", so the escaping
+        decision and the filter loop can never disagree.
+        """
+        if not self._sandbox or self._allowed_filters is None:
+            return True
+        return fname in self._allowed_filters
+
+    #: Node kinds that are TAGS a template author writes, mapped to the name
+    #: they type. Kinds absent from this map are structure (text, output,
+    #: comment, extends/block markers) and are never gated - blocking those
+    #: would stop the template rendering at all rather than restrict it.
+    _GATEABLE_TAGS = {
+        "if": "if",
+        "for": "for",
+        "set": "set",
+        "set_block": "set",
+        "include": "include",
+        "macro": "macro",
+        "from_import": "from",
+        "import_as": "import",
+        "cache": "cache",
+        "spaceless": "spaceless",
+        "autoescape": "autoescape",
+        "live": "live",
+    }
+
+    def _tag_permitted(self, kind: str) -> bool:
+        """Is this tag permitted under the current sandbox?
+
+        One gate for every tag, so the allow-list governs the whole tag
+        vocabulary instead of whichever names somebody remembered to check.
+        """
+        if not self._sandbox or self._allowed_tags is None:
+            return True
+        tag = self._GATEABLE_TAGS.get(kind)
+        if tag is None:
+            return True  # structural node, not an author-written tag
+        return tag in self._allowed_tags
+
     def unsandbox(self):
         """Disable sandbox mode."""
         self._sandbox = False
@@ -2017,6 +2063,14 @@ class Frond:
             if node.strip_before and output:
                 output[-1] = output[-1].rstrip()
 
+            # Sandbox: ONE tag gate, here at dispatch, so every tag is gated by
+            # construction and a tag added later is gated the day it is added.
+            # This replaced a single per-name conditional that covered `include`
+            # only, which let `{% autoescape false %}` turn escaping OFF from
+            # inside a sandbox that had not allowed it (audit feature 38, P1b).
+            if not self._tag_permitted(kind):
+                continue
+
             if kind == "output":
                 result = self._eval_var(node.expr, context)
                 output.append(self._to_output(result))
@@ -2042,10 +2096,9 @@ class Frond:
                     )
 
             elif kind == "include":
-                # Sandbox: check tag
-                if not (self._sandbox and self._allowed_tags is not None
-                        and "include" not in self._allowed_tags):
-                    output.append(self._handle_include(node.content, context))
+                # The sandbox tag gate now runs once at dispatch (above), so the
+                # per-name conditional that used to live here is gone.
+                output.append(self._handle_include(node.content, context))
 
             elif kind == "macro":
                 self._handle_macro(node, context)
@@ -2275,7 +2328,14 @@ class Frond:
         # the var_name eval lets a parenthesised pipe like `{{ (a|f) }}` resolve
         # too — the old code returned empty for that.
         value = _eval_expr(var_name, context, self._apply_filters)
-        is_safe = any(name in ("raw", "safe") for name, _ in filters)
+        # `raw`/`safe` suppress escaping only if the sandbox PERMITS them to run.
+        # Reading the filter name straight out of the parsed source meant a
+        # sandbox that DENIED raw still marked the value safe, so denying raw
+        # produced byte-identical output to allowing it (audit feature 38, P1).
+        is_safe = any(
+            name in ("raw", "safe") and self._filter_permitted(name)
+            for name, _ in filters
+        )
         value = self._apply_filters(value, filters, context)
 
         # Auto-escape HTML unless marked safe or SafeString

{tina4_python-3.13.91 → tina4_python-3.13.94}/tina4_python/messenger/__init__.py

@@ -106,6 +106,11 @@ class Messenger:
                  encryption: str = None, use_tls: bool = None,
                  imap_host: str = None, imap_port: int = None):
         # SMTP (send) — priority: constructor > .env > sensible default
+        # Whether a host was actually CONFIGURED, which is not the same as
+        # self.host being set: self.host falls back to "localhost", so it is never
+        # empty and cannot answer "can this messenger send?". The dev-capture gate
+        # needs that answer, so record it here while the real inputs are in scope.
+        self._smtp_configured = bool(host or os.environ.get("TINA4_MAIL_HOST"))
         self.host = host or os.environ.get("TINA4_MAIL_HOST", "localhost")
         self.port = port or int(os.environ.get("TINA4_MAIL_PORT", "587"))
         self.username = username or os.environ.get("TINA4_MAIL_USERNAME", "")
@@ -141,6 +146,37 @@ class Messenger:
         """Add a default header to all outgoing emails."""
         self._default_headers[name] = value
 
+    def _should_capture(self) -> bool:
+        """Should send() capture to a local mailbox instead of talking to SMTP?
+
+        Availability decides, not verbosity. With no SMTP host configured sending
+        is impossible, so simulate it into a folder rather than failing -- that is
+        what makes a laptop with no mail server usable. ``TINA4_MAIL_CAPTURE``
+        forces capture even when a host IS configured, for anyone who wants
+        "never send real mail from this box".
+
+        ``TINA4_DEBUG`` deliberately does NOT gate this. Debug must still be able
+        to send: tying capture to it means nobody can test a real send from a dev
+        box, which is the common case.
+        """
+        from tina4_python.dotenv import is_truthy
+        if is_truthy(os.environ.get("TINA4_MAIL_CAPTURE", "")):
+            return True
+        return not self._smtp_configured
+
+    def _dev_mailbox(self) -> "DevMailbox":
+        """The local mailbox, created on first capture and reused after.
+
+        Attached lazily so a messenger that never captures never grows the
+        attribute -- callers test ``hasattr(messenger, "dev_mailbox")`` to ask
+        "is this a capturing messenger?".
+        """
+        mailbox = getattr(self, "dev_mailbox", None)
+        if mailbox is None:
+            mailbox = DevMailbox()
+            self.dev_mailbox = mailbox
+        return mailbox
+
     def send(self, to: str | list[str], subject: str, body: str,
              html: bool = False, text: str = None,
              cc: str | list[str] = None,
@@ -167,6 +203,21 @@ class Messenger:
         cc_list = [cc] if isinstance(cc, str) else list(cc or [])
         bcc_list = [bcc] if isinstance(bcc, str) else list(bcc or [])
 
+        # Dev capture is a BRANCH here, not a method swapped onto the instance.
+        # The swap was the cause of tina4-nodejs#42 in Python: dev_send declared
+        # (to, subject, body, html, cc, ...) while this method declares
+        # (to, subject, body, html, text, cc, ...), so one name meant two
+        # signatures -- send(to, subj, body, True, "plain text") filed the
+        # plain-text body as a CC RECIPIENT and reported success, and
+        # send(text=...) raised TypeError on a dev messenger.
+        if self._should_capture():
+            return self._dev_mailbox().capture(
+                to, subject, body, html, text,
+                cc=cc_list, bcc=bcc_list, reply_to=reply_to,
+                from_address=self.from_address, from_name=self.from_name,
+                attachments=attachments,
+            )
+
         has_attachments = bool(attachments)
         has_text_alt = text is not None and html
 
@@ -728,24 +779,44 @@ class DevMailbox:
         self._inbox_dir.mkdir(exist_ok=True)
 
     def capture(self, to: str | list[str], subject: str, body: str,
-                html: bool = False, cc: list[str] = None,
-                bcc: list[str] = None, reply_to: str = None,
+                html: bool = False, text: str = None,
+                cc: str | list[str] = None,
+                bcc: str | list[str] = None, reply_to: str = None,
                 from_address: str = "", from_name: str = "",
                 attachments: list = None) -> dict:
-        """Capture a message to the local outbox (instead of sending via SMTP)."""
+        """Capture a message to the local outbox (instead of sending via SMTP).
+
+        The parameter order MATCHES ``Messenger.send`` on purpose. It did not
+        before: send's 5th positional was ``text`` and capture's was ``cc``, so the
+        same call meant different things depending on which door it came through --
+        that mismatch IS tina4-nodejs#42.
+
+        BREAKING: ``text`` is now the 5th positional. A caller passing ``cc``
+        positionally must switch to the keyword form. Aligning the two signatures
+        is the fix; leaving them apart would preserve the bug.
+
+        cc/bcc are normalised HERE, at the boundary, so a message is well formed
+        however it arrived. Normalising in one caller only (which is what Python
+        did -- in dev_send, never in capture) means a direct caller stores a
+        malformed message and is told it succeeded, and a dev mailbox that accepts
+        a broken message defeats its own purpose.
+        """
         msg_id = f"{int(time.time() * 1000)}_{id(subject) & 0xFFFF:04x}"
         to_list = [to] if isinstance(to, str) else list(to)
+        cc_list = [cc] if isinstance(cc, str) else list(cc or [])
+        bcc_list = [bcc] if isinstance(bcc, str) else list(bcc or [])
 
         message = {
             "id": msg_id,
             "type": "outbox",
             "from": f"{from_name} <{from_address}>" if from_name else from_address,
             "to": to_list,
-            "cc": cc or [],
-            "bcc": bcc or [],
+            "cc": cc_list,
+            "bcc": bcc_list,
             "reply_to": reply_to or "",
             "subject": subject,
             "body": body,
+            "text": text,
             "html": html,
             "attachments": [
                 a if isinstance(a, str) else a.get("filename", "attachment")
@@ -909,31 +980,22 @@ def _is_dev_mode() -> bool:
 def create_messenger(**kwargs) -> Messenger:
     """Factory that returns a Messenger configured for the current environment.
 
-    In dev mode (TINA4_DEBUG=true), email sending is intercepted
-    by DevMailbox — no SMTP connection needed. The original Messenger.send()
-    is replaced with a local capture.
+    Returns ONE concrete type, always. When sending is impossible (no SMTP host
+    configured) or suppressed (``TINA4_MAIL_CAPTURE``), ``send()`` captures to a
+    local ``DevMailbox`` instead -- decided by a branch inside ``send()``, so the
+    object you get back has one ``send`` with one signature either way.
+
+    It no longer replaces ``send`` on the instance. That swap installed a function
+    with a DIFFERENT signature than ``Messenger.send`` under the same name, which
+    is how the documented call ``send(to, subj, body, True, "plain text")`` came to
+    file the plain-text body as a CC recipient and report success.
     """
     messenger = Messenger(**kwargs)
 
-    if _is_dev_mode():
-        mailbox = DevMailbox()
-        # Monkey-patch send to capture locally
-        _original_send = messenger.send
-
-        def dev_send(to, subject, body, html=False, cc=None, bcc=None,
-                     reply_to=None, attachments=None, headers=None):
-            return mailbox.capture(
-                to=to, subject=subject, body=body, html=html,
-                cc=[cc] if isinstance(cc, str) else (cc or []),
-                bcc=[bcc] if isinstance(bcc, str) else (bcc or []),
-                reply_to=reply_to,
-                from_address=messenger.from_address,
-                from_name=messenger.from_name,
-                attachments=attachments,
-            )
-
-        messenger.send = dev_send
-        messenger.dev_mailbox = mailbox
+    # Attach the mailbox eagerly when this messenger will capture, so callers can
+    # inspect it (and the dev admin panel can list it) before the first send.
+    if messenger._should_capture():
+        messenger.dev_mailbox = DevMailbox()
 
     return messenger