l3io-wordpress-database 0.3.5__py3-none-any.whl

l3io/wp/database/_passphrase.py

@@ -0,0 +1,237 @@
+"""Passphrase age streaming: binder preferred, age+batchpass CLI fallback.
+
+Selection via ``L3IO_AGE_PASSPHRASE_BACKEND``:
+
+- ``auto`` (default): binder if importable, else CLI if ``age`` and
+  ``age-plugin-batchpass`` are on ``PATH``
+- ``binder`` / ``cli``: that backend only
+
+Passphrases never appear on argv. The CLI path uses ``AGE_PASSPHRASE_FD``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import subprocess
+import threading
+from typing import IO, Any, Literal
+
+from .errors import CorruptDumpError, DecryptionError, InvalidArgumentsError, MissingDependencyError
+
+BackendName = Literal["binder", "cli"]
+_ENV = "L3IO_AGE_PASSPHRASE_BACKEND"
+
+
+def _requested() -> str:
+    return os.environ.get(_ENV, "auto").strip().lower() or "auto"
+
+
+def binder_available() -> bool:
+    try:
+        import l3io_age_passphrase  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def cli_available() -> bool:
+    from ._client import which_absolute
+
+    return which_absolute("age") is not None and which_absolute("age-plugin-batchpass") is not None
+
+
+def resolve_backend() -> BackendName:
+    choice = _requested()
+    if choice not in {"auto", "binder", "cli"}:
+        msg = f"{_ENV} must be auto, binder, or cli (got {choice!r})"
+        raise InvalidArgumentsError(msg)
+    if choice == "binder":
+        if not binder_available():
+            raise MissingDependencyError(extra="encryption", distribution="l3io-age-passphrase")
+        return "binder"
+    if choice == "cli":
+        if not cli_available():
+            msg = (
+                "passphrase CLI backend needs age >=1.3 and age-plugin-batchpass on PATH "
+                f"(set {_ENV}=binder to use the in-process binder instead)"
+            )
+            raise InvalidArgumentsError(msg)
+        return "cli"
+    if binder_available():
+        return "binder"
+    if cli_available():
+        return "cli"
+    raise MissingDependencyError(extra="encryption", distribution="l3io-age-passphrase")
+
+
+def check_ready(passphrase: str) -> None:
+    if passphrase == "":
+        msg = "passphrase must not be empty"
+        raise InvalidArgumentsError(msg)
+    resolve_backend()
+
+
+def encrypt_io(reader: IO[bytes], writer: IO[bytes], passphrase: str) -> None:
+    backend = resolve_backend()
+    if backend == "binder":
+        _binder_encrypt(reader, writer, passphrase)
+    else:
+        _cli_crypt(reader, writer, passphrase, encrypt=True)
+
+
+def decrypt_io(reader: IO[bytes], writer: IO[bytes], passphrase: str) -> None:
+    backend = resolve_backend()
+    if backend == "binder":
+        _binder_decrypt(reader, writer, passphrase)
+    else:
+        _cli_crypt(reader, writer, passphrase, encrypt=False)
+
+
+def _binder() -> Any:
+    try:
+        import l3io_age_passphrase
+    except ImportError as exc:
+        raise MissingDependencyError(
+            extra="encryption",
+            distribution="l3io-age-passphrase",
+        ) from exc
+    return l3io_age_passphrase
+
+
+def _binder_encrypt(reader: IO[bytes], writer: IO[bytes], passphrase: str) -> None:
+    mod = _binder()
+    try:
+        mod.encrypt_io(reader, writer, passphrase)
+    except mod.EncryptError as exc:
+        if str(exc).startswith("BrokenPipeError"):
+            raise BrokenPipeError(str(exc)) from exc
+        raise OSError(str(exc)) from exc
+
+
+def _binder_decrypt(reader: IO[bytes], writer: IO[bytes], passphrase: str) -> None:
+    mod = _binder()
+    try:
+        mod.decrypt_io(reader, writer, passphrase)
+    except BrokenPipeError:
+        raise
+    except mod.DecryptError as exc:
+        text = str(exc)
+        if text == "Decryption failed":
+            msg = "the passphrase cannot decrypt this dump"
+            raise DecryptionError(msg) from exc
+        msg = "the encrypted dump is damaged or not an age file"
+        raise CorruptDumpError(msg) from exc
+    except OSError as exc:
+        if type(exc) is not OSError or exc.errno is not None:
+            raise
+        msg = "the encrypted dump is truncated or damaged"
+        raise CorruptDumpError(msg) from exc
+
+
+def _open_passphrase_fd(passphrase: str) -> int:
+    """Write the passphrase to a pipe; return the inheritable read FD."""
+    read_fd, write_fd = os.pipe()
+    try:
+        os.write(write_fd, passphrase.encode("utf-8") + b"\n")
+    finally:
+        os.close(write_fd)
+    os.set_inheritable(read_fd, True)
+    return read_fd
+
+
+def _cli_crypt(
+    reader: IO[bytes],
+    writer: IO[bytes],
+    passphrase: str,
+    *,
+    encrypt: bool,
+) -> None:
+    from ._client import age_child_env, which_absolute
+
+    age_bin = which_absolute("age")
+    plugin = which_absolute("age-plugin-batchpass")
+    if age_bin is None or plugin is None:
+        msg = "age and age-plugin-batchpass must be on PATH for the CLI passphrase backend"
+        raise InvalidArgumentsError(msg)
+
+    pass_fd = _open_passphrase_fd(passphrase)
+    env = age_child_env(passphrase_fd=pass_fd)
+    args = [age_bin, "-e" if encrypt else "-d", "-j", "batchpass"]
+    try:
+        proc = subprocess.Popen(  # noqa: S603 - absolute age from PATH, fixed args
+            args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            pass_fds=(pass_fd,),
+            env=env,
+            close_fds=True,
+        )
+    finally:
+        os.close(pass_fd)
+
+    stdin = proc.stdin
+    stdout = proc.stdout
+    stderr_pipe = proc.stderr
+    if stdin is None or stdout is None or stderr_pipe is None:
+        proc.kill()
+        msg = "age subprocess pipes were not created"
+        raise OSError(msg)
+
+    write_error: list[BaseException] = []
+
+    def _pump_in() -> None:
+        try:
+            shutil.copyfileobj(reader, stdin)
+            stdin.close()
+        except BaseException as exc:  # noqa: BLE001 - surface on join
+            write_error.append(exc)
+            with contextlib.suppress(OSError):
+                stdin.close()
+
+    inlet = threading.Thread(target=_pump_in, name="age-passphrase-stdin", daemon=True)
+    inlet.start()
+    try:
+        shutil.copyfileobj(stdout, writer)
+    finally:
+        stdout.close()
+        inlet.join(timeout=3600)
+        stderr = stderr_pipe.read()
+        stderr_pipe.close()
+        code = proc.wait(timeout=60)
+
+    if write_error:
+        exc = write_error[0]
+        if isinstance(exc, BrokenPipeError):
+            raise BrokenPipeError(str(exc)) from exc
+        if isinstance(exc, OSError):
+            raise exc
+        raise OSError(str(exc)) from exc
+
+    if code == 0:
+        return
+
+    err = stderr.decode("utf-8", errors="replace")
+    _map_cli_failure(encrypt=encrypt, err=err, code=code)
+
+
+def _map_cli_failure(*, encrypt: bool, err: str, code: int) -> None:
+    lower = err.lower()
+    if not encrypt:
+        if "no identity matched" in lower or "incorrect" in lower or "wrong" in lower:
+            msg = "the passphrase cannot decrypt this dump"
+            raise DecryptionError(msg)
+        if "failed to read header" in lower or "not an age" in lower or "parsing" in lower:
+            msg = "the encrypted dump is damaged or not an age file"
+            raise CorruptDumpError(msg)
+        # Truncated STREAM bodies often surface as read/MAC errors.
+        if "unexpected eof" in lower or "mac" in lower or "truncated" in lower:
+            msg = "the encrypted dump is truncated or damaged"
+            raise CorruptDumpError(msg)
+        msg = "the encrypted dump is damaged or not an age file"
+        raise CorruptDumpError(msg)
+    detail = err.strip() or "unknown error"
+    msg = f"age passphrase encrypt failed (exit {code}): {detail}"
+    raise OSError(msg)

l3io/wp/database/_sql.py

@@ -0,0 +1,79 @@
+"""Opening a server connection and classifying driver errors. Internal."""
+
+from __future__ import annotations
+
+import pymysql
+
+from .connection import Connection
+from .credentials import ResolvedCredentials
+from .state import ConnectionState
+
+# BaseException is used by classify so SSLError (not a MySQLError) maps to TLS_FAILED.
+
+CONNECT_TIMEOUT_SECONDS = 10
+
+ER_DBACCESS_DENIED = 1044
+ER_ACCESS_DENIED = 1045
+ER_BAD_DB = 1049
+ER_NONEXISTING_GRANT = 1141
+ER_TABLEACCESS_DENIED = 1142
+ER_CANNOT_USER = 1396
+
+
+def open_connection(
+    connection: Connection, credentials: ResolvedCredentials, *, database: str | None
+) -> pymysql.connections.Connection:
+    """Open a connection. Credentials are call arguments, never a URI.
+
+    Auth plugins that would send or prompt for a cleartext password are refused
+    via ``auth_plugin_map`` (see :mod:`.auth`).
+    """
+    from .auth import auth_plugin_map
+    from .tls import pymysql_ssl
+
+    ssl_ctx = pymysql_ssl(connection.tls)
+    return pymysql.connect(
+        host=connection.host,
+        port=connection.port,
+        user=credentials.username,
+        password=credentials.password,
+        database=database,
+        connect_timeout=CONNECT_TIMEOUT_SECONDS,
+        autocommit=False,
+        ssl=ssl_ctx,
+        auth_plugin_map=auth_plugin_map(),
+    )
+
+
+def error_code(exc: pymysql.err.MySQLError) -> int | None:
+    """The server error number, when the driver reports one."""
+    code = exc.args[0] if exc.args else None
+    return code if isinstance(code, int) else None
+
+
+def classify(exc: BaseException) -> ConnectionState:
+    """Map a connection failure onto a :class:`ConnectionState`."""
+    from .tls import is_tls_failure
+
+    if is_tls_failure(exc):
+        return ConnectionState.TLS_FAILED
+    if isinstance(exc, pymysql.err.MySQLError):
+        code = error_code(exc)
+        if code == ER_ACCESS_DENIED:
+            return ConnectionState.AUTHENTICATION_FAILED
+        if code == ER_DBACCESS_DENIED:
+            return ConnectionState.ACCESS_DENIED
+        if code == ER_BAD_DB:
+            return ConnectionState.DATABASE_ABSENT
+    return ConnectionState.UNREACHABLE
+
+
+def literal(fragment: str) -> str:
+    """Protect an SQL fragment that is pasted into a statement executed WITH arguments.
+
+    PyMySQL substitutes arguments with Python ``%``-formatting whenever any are
+    passed, so a ``%`` inside a quoted identifier (MySQL allows it in database
+    names) would be read as a format directive. Statements executed without
+    arguments must not use this: there the ``%`` is sent as written.
+    """
+    return fragment.replace("%", "%%")

l3io/wp/database/_version.py

@@ -0,0 +1,24 @@
+"""The package version, read back from installed distribution metadata.
+
+This module holds no version literal, and neither does ``pyproject.toml``. The
+git tag is the single source: ``hatch-vcs`` derives the distribution version from
+it at build time (AD-30), and this reads that value back. So "keep the tag and
+the package version in sync" is not a rule that can be broken -- there is only
+one value, and the tag decides it.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: Distribution name, which is what carries the version metadata.
+_DISTRIBUTION = "l3io-wordpress-database"
+
+try:
+    __version__ = version(_DISTRIBUTION)
+except PackageNotFoundError:  # pragma: no cover - a source tree never installed
+    # Deliberately sorts below every real release, so an uninstalled tree can
+    # never be mistaken for a newer one.
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

l3io/wp/database/_version_map.py

@@ -0,0 +1,35 @@
+"""WordPress ``$wp_db_version`` to release number.
+
+GENERATED FILE -- do not edit by hand.
+Regenerate with: uv run python tools/generate_version_map.py
+
+Derived from 328 of 328 released versions at or above
+WordPress 5.0, listed by api.wordpress.org/core/stable-check/1.0/,
+reading $wp_db_version from wp-includes/version.php at each release tag.
+
+MIN_RELEASE = '5.0'
+"""
+
+from __future__ import annotations
+
+#: db_version -> the earliest WordPress release that reported it.
+DB_VERSION_TO_RELEASE: dict[int, str] = {
+    43764: "5.0",
+    44719: "5.1",
+    45805: "5.3",
+    47018: "5.4",
+    48748: "5.5",
+    49752: "5.6",
+    51917: "5.9",
+    53496: "6.0.1",
+    55853: "6.3",
+    56657: "6.4",
+    57155: "6.5",
+    58975: "6.7",
+    60421: "6.8.2",
+    60717: "6.9",
+    61833: "7.0",
+}
+
+#: Oldest release included, as a support decision.
+MIN_RELEASE = "5.0"

l3io/wp/database/auth.py

@@ -0,0 +1,64 @@
+"""Authentication-plugin policy for every PyMySQL connection.
+
+A server chooses the auth method. PyMySQL will honour ``mysql_clear_password``
+(password bytes on the wire), ``mysql_old_password``, and ``dialog``. An
+attacker who presents a valid TLS certificate and asks for cleartext auth can
+collect the administrator password. Connections opened by this package therefore
+refuse those plugins and allow only the hashed methods below (plus MariaDB's
+``client_ed25519``, which PyMySQL already implements).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .errors import AuthPluginRefusedError
+
+#: Plugins this package will complete a handshake for.
+ALLOWED_AUTH_PLUGINS: frozenset[str] = frozenset(
+    {
+        "mysql_native_password",
+        "caching_sha2_password",
+        "sha256_password",
+        "client_ed25519",  # MariaDB; built into PyMySQL
+    }
+)
+
+#: Plugins PyMySQL would otherwise honour that send or prompt for a password
+#: in a form we refuse. Mapped to a refusing handler via :func:`auth_plugin_map`.
+REFUSED_AUTH_PLUGINS: frozenset[str] = frozenset(
+    {
+        "mysql_clear_password",
+        "mysql_old_password",
+        "dialog",
+    }
+)
+
+
+def _refuse_class(plugin: str) -> Callable[[Any], Any]:
+    """A PyMySQL ``auth_plugin_map`` handler that refuses ``plugin``."""
+
+    class _Refuse:
+        def __init__(self, connection: object) -> None:
+            self.connection = connection
+
+        def authenticate(self, packet: object) -> None:
+            del packet
+            msg = f"authentication plugin {plugin!r} is not allowed"
+            raise AuthPluginRefusedError(plugin, msg)
+
+        def prompt(self, echo: bool, prompt: object) -> str:
+            # dialog falls back to prompt() if authenticate is missing; keep both.
+            del echo, prompt
+            msg = f"authentication plugin {plugin!r} is not allowed"
+            raise AuthPluginRefusedError(plugin, msg)
+
+    _Refuse.__name__ = f"Refuse_{plugin}"
+    _Refuse.__qualname__ = f"Refuse_{plugin}"
+    return _Refuse
+
+
+def auth_plugin_map() -> dict[str, Callable[[Any], Any]]:
+    """Handlers that raise :class:`AuthPluginRefusedError` for refused plugins."""
+    return {name: _refuse_class(name) for name in sorted(REFUSED_AUTH_PLUGINS)}