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

l3io/wp/database/server.py

@@ -0,0 +1,139 @@
+"""Which server this is, and what the session's own account may do."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from opentelemetry import trace
+
+#: Floors: MariaDB 10.1 rejects ALTER USER, which provisioning needs.
+_FLOOR = {"mysql": (8, 0, 0), "mariadb": (10, 2, 0)}
+
+#: Upstream end of life, per (family, major, minor) series. Data, not logic:
+#: extend it as series retire.
+_END_OF_LIFE: frozenset[tuple[str, int, int]] = frozenset(
+    {
+        ("mysql", 5, 7),
+        ("mysql", 8, 0),
+        # Innovation releases are supported only until the next one ships.
+        ("mysql", 8, 1),
+        ("mysql", 8, 2),
+        ("mysql", 8, 3),
+        *(("mysql", 9, minor) for minor in range(7)),
+        ("mariadb", 10, 1),
+        ("mariadb", 10, 2),
+        ("mariadb", 10, 3),
+        ("mariadb", 10, 4),
+        ("mariadb", 10, 5),
+        ("mariadb", 10, 6),  # LTS, ended July 2026
+        # Short-term releases between the 10.11 and 11.4 LTS lines.
+        ("mariadb", 11, 0),
+        ("mariadb", 11, 1),
+        ("mariadb", 11, 2),
+        ("mariadb", 11, 3),
+    }
+)
+
+_VERSION = re.compile(r"^(\d+)\.(\d+)\.(\d+)")
+
+
+class ServerFamily(StrEnum):
+    """The two server families this package supports."""
+
+    MYSQL = "mysql"
+    MARIADB = "mariadb"
+
+
+@dataclass(frozen=True, slots=True)
+class ServerInfo:
+    """A server's family and version."""
+
+    family: ServerFamily
+    version: tuple[int, int, int]
+    version_text: str
+
+    @property
+    def is_supported(self) -> bool:
+        return self.version >= _FLOOR[self.family.value]
+
+    @property
+    def is_end_of_life(self) -> bool:
+        major, minor, _ = self.version
+        return (self.family.value, major, minor) in _END_OF_LIFE or not self.is_supported
+
+
+def parse_version(text: str) -> ServerInfo:
+    """Interpret ``SELECT VERSION()``."""
+    match = _VERSION.match(text)
+    if match is None:
+        msg = f"unrecognised server version {text!r}"
+        raise ValueError(msg)
+    major, minor, patch = (int(g) for g in match.groups())
+    family = ServerFamily.MARIADB if "mariadb" in text.lower() else ServerFamily.MYSQL
+    return ServerInfo(family, (major, minor, patch), text)
+
+
+def detect_server(cursor: Any) -> ServerInfo:
+    """Ask the server what it is."""
+    cursor.execute("SELECT VERSION()")
+    info = parse_version(str(cursor.fetchone()[0]))
+    # Every detection happens inside an operation's span (spec §8).
+    trace.get_current_span().set_attribute("db.system", info.family.value)
+    return info
+
+
+def grantee(user: str, host: str) -> str:
+    """The ``GRANTEE`` form ``information_schema`` uses."""
+    return f"'{user}'@'{host}'"
+
+
+@dataclass(frozen=True, slots=True)
+class Privileges:
+    """What the session's own account holds on one database."""
+
+    names: frozenset[str]
+    grantable: bool
+    unverified: bool
+    #: Only the privileges held on ``*.*``; ``names`` also holds database-level ones.
+    global_names: frozenset[str] = frozenset()
+
+    def has(self, name: str) -> bool:
+        return self.grantable if name == "GRANT OPTION" else name in self.names
+
+    def has_global(self, name: str) -> bool:
+        return name in self.global_names
+
+
+def account_privileges(cursor: Any, database: str) -> Privileges:
+    """Global and database-level privileges of the session's own account.
+
+    ``unverified`` is set when a role is active: ``information_schema`` lists
+    only directly granted privileges, so a role-held privilege would read as
+    missing.
+    """
+    cursor.execute("SELECT CURRENT_USER()")
+    user, _, host = str(cursor.fetchone()[0]).rpartition("@")
+    cursor.execute("SELECT CURRENT_ROLE()")
+    role = cursor.fetchone()[0]
+    unverified = role is not None and str(role).upper() != "NONE"
+
+    who = grantee(user, host)
+    cursor.execute(
+        "SELECT PRIVILEGE_TYPE, IS_GRANTABLE FROM information_schema.USER_PRIVILEGES "
+        "WHERE GRANTEE = %s",
+        (who,),
+    )
+    rows = list(cursor.fetchall())
+    global_names = frozenset(str(r[0]) for r in rows)
+    cursor.execute(
+        "SELECT PRIVILEGE_TYPE, IS_GRANTABLE FROM information_schema.SCHEMA_PRIVILEGES "
+        "WHERE GRANTEE = %s AND %s LIKE TABLE_SCHEMA",
+        (who, database),
+    )
+    rows += list(cursor.fetchall())
+    names = frozenset(str(r[0]) for r in rows)
+    grantable = any(str(r[1]).upper() == "YES" for r in rows)
+    return Privileges(names, grantable, unverified, global_names)

l3io/wp/database/state.py

@@ -0,0 +1,82 @@
+"""Outcomes of inspecting a database's state.
+
+"Does this database exist?" answered with a bare boolean, from a method that
+catches every exception and returns ``False``, makes "absent", "wrong password"
+and "host unreachable" indistinguishable -- and since the caller's next move is
+to create objects using *administrative* credentials, collapsing those cases is
+the dangerous part, not a cosmetic one.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ConnectionState(StrEnum):
+    """Why an attempt to use a database succeeded or failed."""
+
+    READY = "ready"
+    """Connected, authenticated, and the database is usable."""
+
+    DATABASE_ABSENT = "database_absent"
+    """Authenticated, but the target database does not exist.
+
+    Only observable once the account itself exists: the server authenticates
+    before it resolves the database, so a site with neither reports
+    :attr:`AUTHENTICATION_FAILED` instead. Verified against MySQL 8.0.
+    """
+
+    ACCESS_DENIED = "access_denied"
+    """Authenticated, but this account may not use the target database."""
+
+    AUTHENTICATION_FAILED = "authentication_failed"
+    """The server was reached and rejected the credentials."""
+
+    UNREACHABLE = "unreachable"
+    """The server could not be reached."""
+
+    TLS_FAILED = "tls_failed"
+    """The server was contacted but TLS was required and failed."""
+
+    AUTH_PLUGIN_REFUSED = "auth_plugin_refused"
+    """The server asked for an authentication plugin this package refuses."""
+
+    CREDENTIALS_UNOBTAINABLE = "credentials_unobtainable"
+    """Credentials could not be obtained, so nothing was attempted."""
+
+    @property
+    def is_ready(self) -> bool:
+        """Whether the database is usable as configured."""
+        return self is ConnectionState.READY
+
+    @property
+    def needs_provisioning(self) -> bool:
+        """Whether provisioning with administrative credentials could fix this.
+
+        Authentication failure counts. Before first provisioning the WordPress
+        account does not exist yet, so inspecting as that account *must* fail --
+        treating that as a refusal to provision would reject the single most
+        common case this package exists for: a database created by
+        ``wp db create`` or a MySQL container's ``MYSQL_DATABASE``, with no user
+        yet. The administrator is the authority on what exists, not the failed
+        login of an account that is the whole point of the operation.
+        """
+        return self in {
+            ConnectionState.DATABASE_ABSENT,
+            ConnectionState.AUTHENTICATION_FAILED,
+            ConnectionState.ACCESS_DENIED,
+        }
+
+    @property
+    def blocks_provisioning(self) -> bool:
+        """Whether provisioning cannot proceed, whatever credentials are held.
+
+        An unreachable server or unobtainable credentials say nothing about
+        what exists, so nothing may be created on the strength of them.
+        """
+        return self in {
+            ConnectionState.UNREACHABLE,
+            ConnectionState.TLS_FAILED,
+            ConnectionState.AUTH_PLUGIN_REFUSED,
+            ConnectionState.CREDENTIALS_UNOBTAINABLE,
+        }

l3io/wp/database/tls.py

@@ -0,0 +1,211 @@
+"""TLS settings for database connections.
+
+AD-3 keeps the site descriptor free of credentials; TLS is about *how* the
+host is reached, so it lives on :class:`~l3io.wp.database.Connection` rather
+than on a credential source. The same settings drive PyMySQL and the client
+option-file pipe (ADR-0002).
+"""
+
+from __future__ import annotations
+
+import ssl
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from .errors import InvalidArgumentsError
+from .server import ServerFamily
+
+#: Hosts treated as local by :func:`tls_required_unless_local`.
+DEFAULT_LOCAL_HOSTS: frozenset[str] = frozenset(
+    {
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        "0:0:0:0:0:0:0:1",
+    }
+)
+
+
+class TlsMode(StrEnum):
+    """How strongly TLS is required for a connection."""
+
+    OFF = "off"
+    """No TLS. Today's default; plaintext TCP."""
+
+    REQUIRED = "required"
+    """TLS required; server certificate is not verified."""
+
+    VERIFY_CA = "verify_ca"
+    """TLS required; certificate chain verified against a CA (hostname not checked)."""
+
+    VERIFY_IDENTITY = "verify_identity"
+    """TLS required; certificate chain and hostname verified."""
+
+
+@dataclass(frozen=True, slots=True)
+class TlsSettings:
+    """TLS options for one :class:`~l3io.wp.database.Connection`."""
+
+    mode: TlsMode = TlsMode.OFF
+    ca_file: Path | None = None
+    cert_file: Path | None = None
+    key_file: Path | None = None
+
+    def __post_init__(self) -> None:
+        if self.mode is TlsMode.OFF:
+            if self.ca_file is not None or self.cert_file is not None or self.key_file is not None:
+                msg = "ca_file, cert_file and key_file require a TLS mode other than OFF"
+                raise InvalidArgumentsError(msg)
+            return
+        if (self.cert_file is None) ^ (self.key_file is None):
+            msg = "cert_file and key_file must be supplied together"
+            raise InvalidArgumentsError(msg)
+        if self.mode in (TlsMode.VERIFY_CA, TlsMode.VERIFY_IDENTITY) and self.ca_file is None:
+            # System store is allowed: ca_file None means the default context CAs.
+            return
+        for label, path in (
+            ("ca_file", self.ca_file),
+            ("cert_file", self.cert_file),
+            ("key_file", self.key_file),
+        ):
+            if path is not None and not isinstance(path, Path):
+                msg = f"{label} must be a Path, not {type(path).__name__}"
+                raise InvalidArgumentsError(msg)
+
+
+def tls_required_unless_local(
+    host: str,
+    *,
+    local_hosts: frozenset[str] = DEFAULT_LOCAL_HOSTS,
+    ca_file: Path | None = None,
+    cert_file: Path | None = None,
+    key_file: Path | None = None,
+) -> TlsSettings:
+    """Require verified TLS for non-local hosts; leave local hosts plaintext.
+
+    ``localhost``, ``127.0.0.1`` and ``::1`` (and any extra names in
+    ``local_hosts``) get :attr:`TlsMode.OFF`. Everything else gets
+    :attr:`TlsMode.VERIFY_IDENTITY` against ``ca_file`` or the system store.
+    """
+    if not host:
+        msg = "host must not be empty"
+        raise InvalidArgumentsError(msg)
+    if host.lower() in {h.lower() for h in local_hosts}:
+        return TlsSettings(mode=TlsMode.OFF)
+    return TlsSettings(
+        mode=TlsMode.VERIFY_IDENTITY,
+        ca_file=ca_file,
+        cert_file=cert_file,
+        key_file=key_file,
+    )
+
+
+def pymysql_ssl(settings: TlsSettings) -> ssl.SSLContext | None:
+    """An :class:`ssl.SSLContext` for PyMySQL, or ``None`` when TLS is off."""
+    if settings.mode is TlsMode.OFF:
+        return None
+    if settings.mode is TlsMode.REQUIRED:
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    else:
+        ctx = ssl.create_default_context(cafile=_path_str(settings.ca_file))
+        if settings.mode is TlsMode.VERIFY_CA:
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_REQUIRED
+        else:
+            ctx.check_hostname = True
+            ctx.verify_mode = ssl.CERT_REQUIRED
+    if settings.cert_file is not None and settings.key_file is not None:
+        ctx.load_cert_chain(str(settings.cert_file), str(settings.key_file))
+    return ctx
+
+
+def option_file_lines(settings: TlsSettings, family: ServerFamily) -> tuple[str, ...]:
+    """``[client]`` TLS lines for one client family.
+
+    MySQL 8.4 rejects ``ssl=1`` (``ssl-mode`` only). MariaDB rejects
+    ``ssl-mode`` (``ssl`` plus ``ssl-verify-server-cert`` for verify modes).
+    Never use the ``loose-`` prefix: an unknown security option must fail
+    loudly, not skip verification.
+    """
+    if settings.mode is TlsMode.OFF:
+        return ()
+    lines: list[str] = []
+    if family is ServerFamily.MYSQL:
+        lines.append(f"ssl-mode={_client_ssl_mode(settings.mode)}")
+    else:
+        lines.append("ssl=1")
+        if settings.mode in (TlsMode.VERIFY_CA, TlsMode.VERIFY_IDENTITY):
+            lines.append("ssl-verify-server-cert=1")
+    if settings.ca_file is not None:
+        lines.append(f"ssl-ca={_quote_path(settings.ca_file)}")
+    if settings.cert_file is not None:
+        lines.append(f"ssl-cert={_quote_path(settings.cert_file)}")
+    if settings.key_file is not None:
+        lines.append(f"ssl-key={_quote_path(settings.key_file)}")
+    return tuple(lines)
+
+
+def is_tls_failure(exc: BaseException) -> bool:
+    """Whether a connect failure is a TLS/SSL problem rather than plain unreachability."""
+    if isinstance(exc, ssl.SSLError):
+        return True
+    text = str(exc).lower()
+    markers = (
+        "ssl",
+        "tls",
+        "certificate",
+        "cert verify",
+        "certificate verify failed",
+        "wrong version number",
+        "handshake",
+    )
+    return any(m in text for m in markers)
+
+
+def is_verification_failure(exc: BaseException) -> bool:
+    """Whether a TLS failure is specifically certificate verification."""
+    if isinstance(exc, ssl.SSLCertVerificationError):
+        return True
+    text = str(exc).lower()
+    markers = (
+        "certificate verify failed",
+        "certificate_verify_failed",
+        "hostname mismatch",
+        "certificate has expired",
+        "self-signed certificate",
+        "unable to get local issuer",
+    )
+    return any(m in text for m in markers)
+
+
+def _client_ssl_mode(mode: TlsMode) -> str:
+    return {
+        TlsMode.REQUIRED: "REQUIRED",
+        TlsMode.VERIFY_CA: "VERIFY_CA",
+        TlsMode.VERIFY_IDENTITY: "VERIFY_IDENTITY",
+    }[mode]
+
+
+def _path_str(path: Path | None) -> str | None:
+    return None if path is None else str(path)
+
+
+def _quote_path(path: Path) -> str:
+    """Quote a filesystem path for an option-file value (same escaping as credentials)."""
+    value = str(path)
+    if "\x00" in value:
+        msg = "a TLS path cannot contain a NUL character"
+        raise InvalidArgumentsError(msg)
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    try:
+        size = len(escaped.encode())
+    except UnicodeEncodeError as exc:
+        msg = "a TLS path is not valid UTF-8 text"
+        raise InvalidArgumentsError(msg) from exc
+    if size > 1024:
+        msg = "a TLS path is longer than 1024 bytes once escaped"
+        raise InvalidArgumentsError(msg)
+    return f'"{escaped}"'