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

l3io/wp/database/facade.py

@@ -0,0 +1,220 @@
+"""One object for one site: every operation with the connection bound."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Sequence
+from typing import IO
+
+from . import inspection, provision, transfer
+from .connection import Connection
+from .credentials import CredentialSource
+from .inspection import Survey
+from .provision import EnsureResult, OperationResult
+from .state import ConnectionState
+from .transfer import DropTablesResult, DumpStream, TransferResult
+from .verdict import Verdict
+from .versions import SchemaVersion
+
+
+class Database:
+    """Every operation against one :class:`Connection`.
+
+    The free functions are the primary API; this binds one connection so a
+    single object can serve one site.
+    """
+
+    __slots__ = ("_connection",)
+
+    def __init__(self, connection: Connection) -> None:
+        self._connection = connection
+
+    @property
+    def connection(self) -> Connection:
+        """The site this object operates on."""
+        return self._connection
+
+    def survey(
+        self,
+        admin: CredentialSource,
+        *,
+        wordpress_user: str | None = None,
+        user_host: str = "%",
+        table_prefix: str = "wp_",
+    ) -> Survey:
+        return inspection.survey(
+            self._connection,
+            admin,
+            wordpress_user=wordpress_user,
+            user_host=user_host,
+            table_prefix=table_prefix,
+        )
+
+    def inspect(self, credentials: CredentialSource) -> ConnectionState:
+        return inspection.inspect(self._connection, credentials)
+
+    def schema_version(
+        self, credentials: CredentialSource, table_prefix: str = "wp_"
+    ) -> SchemaVersion | None:
+        return inspection.schema_version(self._connection, credentials, table_prefix)
+
+    def check_ensure(
+        self, admin: CredentialSource, wordpress: CredentialSource, *, user_host: str = "%"
+    ) -> Verdict:
+        return provision.check_ensure(self._connection, admin, wordpress, user_host=user_host)
+
+    def ensure(
+        self,
+        admin: CredentialSource,
+        wordpress: CredentialSource,
+        *,
+        user_host: str = "%",
+        charset: str = "utf8mb4",
+        collation: str = "utf8mb4_unicode_ci",
+    ) -> EnsureResult:
+        return provision.ensure(
+            self._connection,
+            admin,
+            wordpress,
+            user_host=user_host,
+            charset=charset,
+            collation=collation,
+        )
+
+    def check_rotate_password(
+        self, admin: CredentialSource, wordpress: CredentialSource, *, user_host: str = "%"
+    ) -> Verdict:
+        return provision.check_rotate_password(
+            self._connection, admin, wordpress, user_host=user_host
+        )
+
+    def rotate_password(
+        self, admin: CredentialSource, wordpress: CredentialSource, *, user_host: str = "%"
+    ) -> OperationResult:
+        return provision.rotate_password(self._connection, admin, wordpress, user_host=user_host)
+
+    def check_revoke(
+        self, admin: CredentialSource, user: str, *, user_host: str = "%", confirm: str
+    ) -> Verdict:
+        return provision.check_revoke(
+            self._connection, admin, user, user_host=user_host, confirm=confirm
+        )
+
+    def revoke(
+        self, admin: CredentialSource, user: str, *, user_host: str = "%", confirm: str
+    ) -> OperationResult:
+        return provision.revoke(self._connection, admin, user, user_host=user_host, confirm=confirm)
+
+    def check_drop_user(
+        self, admin: CredentialSource, user: str, *, user_host: str = "%", confirm: str
+    ) -> Verdict:
+        return provision.check_drop_user(
+            self._connection, admin, user, user_host=user_host, confirm=confirm
+        )
+
+    def drop_user(
+        self, admin: CredentialSource, user: str, *, user_host: str = "%", confirm: str
+    ) -> OperationResult:
+        return provision.drop_user(
+            self._connection, admin, user, user_host=user_host, confirm=confirm
+        )
+
+    def check_drop_database(self, admin: CredentialSource, *, confirm: str) -> Verdict:
+        return provision.check_drop_database(self._connection, admin, confirm=confirm)
+
+    def drop_database(self, admin: CredentialSource, *, confirm: str) -> OperationResult:
+        return provision.drop_database(self._connection, admin, confirm=confirm)
+
+    def check_dump(self, credentials: CredentialSource, *, options: Sequence[str] = ()) -> Verdict:
+        return transfer.check_dump(self._connection, credentials, options=options)
+
+    def check_drop_tables(self, credentials: CredentialSource, *, prefix: str) -> DropTablesResult:
+        return transfer.check_drop_tables(self._connection, credentials, prefix=prefix)
+
+    def drop_tables(self, credentials: CredentialSource, *, prefix: str) -> DropTablesResult:
+        return transfer.drop_tables(self._connection, credentials, prefix=prefix)
+
+    def iter_dump(
+        self,
+        credentials: CredentialSource,
+        *,
+        recipients: Sequence[str] | None = None,
+        passphrase: str | None = None,
+        options: Sequence[str] = (),
+    ) -> DumpStream:
+        return transfer.iter_dump(
+            self._connection,
+            credentials,
+            recipients=recipients,
+            passphrase=passphrase,
+            options=options,
+        )
+
+    def dump(
+        self,
+        credentials: CredentialSource,
+        to: IO[bytes] | str | os.PathLike[str],
+        *,
+        recipients: Sequence[str] | None = None,
+        passphrase: str | None = None,
+        options: Sequence[str] = (),
+    ) -> TransferResult:
+        return transfer.dump(
+            self._connection,
+            credentials,
+            to,
+            recipients=recipients,
+            passphrase=passphrase,
+            options=options,
+        )
+
+    def check_load(
+        self,
+        credentials: CredentialSource,
+        *,
+        source: str | os.PathLike[str] | None = None,
+        replace: str | None = None,
+        prune_prefix: str | None = None,
+        identities: Sequence[str] | None = None,
+        passphrase: str | None = None,
+        options: Sequence[str] = (),
+        allow_unsandboxed: bool = False,
+    ) -> Verdict:
+        return transfer.check_load(
+            self._connection,
+            credentials,
+            source=source,
+            replace=replace,
+            prune_prefix=prune_prefix,
+            identities=identities,
+            passphrase=passphrase,
+            options=options,
+            allow_unsandboxed=allow_unsandboxed,
+        )
+
+    def load(
+        self,
+        credentials: CredentialSource,
+        source: IO[bytes] | Iterable[bytes] | str | os.PathLike[str],
+        *,
+        replace: str | None = None,
+        prune_prefix: str | None = None,
+        identities: Sequence[str] | None = None,
+        passphrase: str | None = None,
+        options: Sequence[str] = (),
+        allow_unsandboxed: bool = False,
+    ) -> TransferResult:
+        return transfer.load(
+            self._connection,
+            credentials,
+            source,
+            replace=replace,
+            prune_prefix=prune_prefix,
+            identities=identities,
+            passphrase=passphrase,
+            options=options,
+            allow_unsandboxed=allow_unsandboxed,
+        )
+
+    def __repr__(self) -> str:
+        return f"Database({self._connection!r})"

l3io/wp/database/identifiers.py

@@ -0,0 +1,95 @@
+"""Validating and quoting MySQL identifiers.
+
+A database-level ``GRANT`` matches its database name as a ``LIKE`` pattern, so
+``_`` is a single-character wildcard. Granting on ``wp_site`` therefore also
+grants on ``wpXsite``:
+
+    GRANT ALL PRIVILEGES ON `wp_site`.* TO 'victim'@'%';
+    -- victim can then SHOW and CREATE TABLE in wpXsite
+
+Backticks do not suppress this; only escaping the wildcard does. Essentially
+every WordPress database is named with an underscore, so an unescaped
+``GRANT ALL PRIVILEGES ON {n}.*`` over-grants every user it creates.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .errors import InvalidArgumentsError, InvalidDatabaseNameError, InvalidIdentifierError
+
+#: MySQL caps database names at 64 characters. MariaDB allows longer user names
+#: than MySQL's 32, so the stricter MySQL limit is applied to both.
+MAX_DATABASE_NAME = 64
+MAX_USER_NAME = 32
+
+_FORBIDDEN = {"\x00", "\n", "\r", "`", "/", "\\", "."}
+#: The grant lookup compares against the unescaped ``'user'@'host'`` form.
+_FORBIDDEN_IN_USER_NAME = frozenset("'")
+
+
+def _check(kind: str, value: str, limit: int, forbidden: frozenset[str] = frozenset()) -> None:
+    if not isinstance(value, str) or not value:
+        raise InvalidIdentifierError(kind, str(value), "must be a non-empty string")
+    if len(value) > limit:
+        raise InvalidIdentifierError(kind, value, f"longer than {limit} characters")
+    if value != value.strip():
+        raise InvalidIdentifierError(kind, value, "has leading or trailing whitespace")
+    found = (_FORBIDDEN | forbidden).intersection(value)
+    if found:
+        chars = ", ".join(repr(c) for c in sorted(found))
+        raise InvalidIdentifierError(kind, value, f"contains forbidden characters: {chars}")
+
+
+def validate_database_name(name: str) -> str:
+    """Return ``name`` if it is usable as a database identifier, else raise."""
+    try:
+        _check("database name", name, MAX_DATABASE_NAME)
+    except InvalidIdentifierError as exc:
+        raise InvalidDatabaseNameError(str(name), exc.reason) from exc
+    return name
+
+
+def validate_user_name(name: str) -> str:
+    """Return ``name`` if it is usable as a user identifier, else raise."""
+    _check("user name", name, MAX_USER_NAME, _FORBIDDEN_IN_USER_NAME)
+    return name
+
+
+def quote_identifier(name: str) -> str:
+    """Backtick-quote an identifier, doubling any internal backticks."""
+    return "`" + name.replace("`", "``") + "`"
+
+
+def grant_pattern(name: str) -> str:
+    """The database name as the ``LIKE`` pattern a GRANT stores, unquoted.
+
+    ``information_schema.SCHEMA_PRIVILEGES.TABLE_SCHEMA`` holds this form, so
+    comparing against it finds exactly the grant :func:`quote_grant_database`
+    wrote.
+    """
+    return name.replace("\\", "\\\\").replace("_", r"\_").replace("%", r"\%")
+
+
+def quote_grant_database(name: str) -> str:
+    """Quote a database name for the ``ON <db>.*`` clause of a GRANT.
+
+    The clause is matched as a ``LIKE`` pattern, so ``_`` and ``%`` must be
+    escaped or the grant silently widens to every database matching it.
+    """
+    return quote_identifier(grant_pattern(name))
+
+
+_CHARSET = re.compile(r"^[A-Za-z0-9_]+$")
+
+
+def validate_charset(value: str, kind: str) -> str:
+    """Return a character set or collation name, or raise.
+
+    These cannot be parameterised, so they are restricted to the characters
+    every real name uses.
+    """
+    if not isinstance(value, str) or not _CHARSET.match(value):
+        msg = f"{kind} {value!r} is not a valid name"
+        raise InvalidArgumentsError(msg)
+    return value

l3io/wp/database/inspection.py

@@ -0,0 +1,254 @@
+"""Read-only questions about a database, answered by the right account.
+
+:func:`survey` runs as the administrator and is the authority on what exists
+(AD-29). :func:`inspect` is the WordPress account's own login probe: it
+describes the account, never whether the database exists.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import pymysql
+
+from ._observe import operation
+from ._sql import (
+    ER_DBACCESS_DENIED,
+    ER_TABLEACCESS_DENIED,
+    classify,
+    error_code,
+    literal,
+    open_connection,
+)
+from .connection import Connection
+from .credentials import CredentialSource, ResolvedCredentials
+from .errors import (
+    AccessDeniedError,
+    AuthenticationFailedError,
+    ConfigurationError,
+    CredentialsAbsentError,
+    CredentialsUnobtainableError,
+    DatabaseUnreachableError,
+    MissingDependencyError,
+)
+from .identifiers import quote_identifier, validate_user_name
+from .server import ServerInfo, detect_server, grantee
+from .state import ConnectionState
+from .versions import SchemaVersion
+
+
+@dataclass(frozen=True, slots=True)
+class Survey:
+    """What the administrator can see about one database.
+
+    ``table_count`` is every row in ``information_schema.TABLES`` for the
+    schema, so base tables and views both count. Routines and events are
+    separate: they are not tables, and a database that holds only them still
+    reports ``table_count == 0``.
+    """
+
+    server: ServerInfo
+    database_exists: bool
+    table_count: int
+    size_bytes: int
+    is_wordpress: bool
+    schema_version: SchemaVersion | None
+    user_exists: bool | None
+    user_privileges: frozenset[str] | None
+    routine_count: int = 0
+    event_count: int = 0
+
+
+def _resolve(source: CredentialSource) -> ResolvedCredentials:
+    return source.resolve()
+
+
+def _connect_or_raise(
+    connection: Connection, credentials: ResolvedCredentials, database: str | None
+) -> Any:
+    """Open a session, or raise a package error saying why it could not be."""
+    from .errors import AuthPluginRefusedError, TlsHandshakeError, TlsVerificationError
+    from .tls import is_tls_failure, is_verification_failure
+
+    try:
+        return open_connection(connection, credentials, database=database)
+    except AuthPluginRefusedError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - SSLError and driver errors both map here
+        if (
+            isinstance(exc, pymysql.err.MySQLError)
+            and classify(exc) is ConnectionState.AUTHENTICATION_FAILED
+        ):
+            msg = f"the account {credentials.username!r} was rejected"
+            raise AuthenticationFailedError(msg) from exc
+        if is_verification_failure(exc):
+            msg = f"{connection.host}:{connection.port} presented a certificate that did not verify"
+            raise TlsVerificationError(msg) from exc
+        if is_tls_failure(exc) or classify(exc) is ConnectionState.TLS_FAILED:
+            msg = (
+                f"{connection.host}:{connection.port} did not complete a TLS "
+                "handshake (TLS was required)"
+            )
+            raise TlsHandshakeError(msg) from exc
+        msg = f"{connection.host}:{connection.port} could not be reached"
+        raise DatabaseUnreachableError(msg) from exc
+
+
+def _admin_session(connection: Connection, admin: ResolvedCredentials) -> Any:
+    """An admin connection with no default database, or a package error."""
+    return _connect_or_raise(connection, admin, None)
+
+
+def _as_package_error(exc: pymysql.err.MySQLError) -> Exception:
+    """Translate a server error raised mid-session into a package-owned one."""
+    if error_code(exc) in (ER_TABLEACCESS_DENIED, ER_DBACCESS_DENIED):
+        return AccessDeniedError(f"the administrator lacks a privilege the survey needs: {exc}")
+    return DatabaseUnreachableError(f"the server failed during the survey: {exc}")
+
+
+def _read_schema_version(cursor: Any, database: str, table_prefix: str) -> SchemaVersion | None:
+    table = f"{quote_identifier(database)}.{quote_identifier(table_prefix + 'options')}"
+    cursor.execute(
+        f"SELECT option_value FROM {literal(table)} WHERE option_name = %s",  # noqa: S608 - quoted identifiers
+        ("db_version",),
+    )
+    row = cursor.fetchone()
+    if row is None or row[0] is None:
+        return None
+    try:
+        return SchemaVersion(int(row[0]))
+    except (TypeError, ValueError) as exc:
+        msg = f"db_version {row[0]!r} in {table} is not an integer"
+        raise AccessDeniedError(msg) from exc
+
+
+def survey(
+    connection: Connection,
+    admin: CredentialSource,
+    *,
+    wordpress_user: str | None = None,
+    user_host: str = "%",
+    table_prefix: str = "wp_",
+) -> Survey:
+    """Everything the administrator can see about this database and account."""
+    with operation("survey", connection) as fields:
+        session = _admin_session(connection, _resolve(admin))
+        database = connection.database
+        try:
+            with session, session.cursor() as cur:
+                server = detect_server(cur)
+                cur.execute(
+                    "SELECT COUNT(*) FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = %s",
+                    (database,),
+                )
+                exists = int(cur.fetchone()[0]) > 0
+                cur.execute(
+                    "SELECT COUNT(*), COALESCE(SUM(DATA_LENGTH + INDEX_LENGTH), 0) "
+                    "FROM information_schema.TABLES WHERE TABLE_SCHEMA = %s",
+                    (database,),
+                )
+                table_count, size_bytes = (int(v) for v in cur.fetchone())
+                cur.execute(
+                    "SELECT COUNT(*) FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA = %s",
+                    (database,),
+                )
+                routine_count = int(cur.fetchone()[0])
+                cur.execute(
+                    "SELECT COUNT(*) FROM information_schema.EVENTS WHERE EVENT_SCHEMA = %s",
+                    (database,),
+                )
+                event_count = int(cur.fetchone()[0])
+                cur.execute(
+                    "SELECT COUNT(*) FROM information_schema.TABLES "
+                    "WHERE TABLE_SCHEMA = %s AND TABLE_NAME = %s",
+                    (database, f"{table_prefix}options"),
+                )
+                is_wordpress = int(cur.fetchone()[0]) > 0
+                version = (
+                    _read_schema_version(cur, database, table_prefix) if is_wordpress else None
+                )
+
+                user_exists: bool | None = None
+                user_privileges: frozenset[str] | None = None
+                if wordpress_user is not None:
+                    validate_user_name(wordpress_user)
+                    try:
+                        cur.execute(
+                            "SELECT COUNT(*) FROM mysql.user WHERE User = %s AND Host = %s",
+                            (wordpress_user, user_host),
+                        )
+                        user_exists = int(cur.fetchone()[0]) > 0
+                    except pymysql.err.MySQLError as exc:
+                        if error_code(exc) != ER_TABLEACCESS_DENIED:
+                            raise
+                    cur.execute(
+                        "SELECT PRIVILEGE_TYPE FROM information_schema.SCHEMA_PRIVILEGES "
+                        "WHERE GRANTEE = %s AND %s LIKE TABLE_SCHEMA",
+                        (grantee(wordpress_user, user_host), database),
+                    )
+                    user_privileges = frozenset(str(r[0]) for r in cur.fetchall())
+        except pymysql.err.MySQLError as exc:
+            raise _as_package_error(exc) from exc
+        fields.update(
+            database_exists=exists,
+            table_count=table_count,
+            routine_count=routine_count,
+            event_count=event_count,
+            is_wordpress=is_wordpress,
+        )
+        return Survey(
+            server,
+            exists,
+            table_count,
+            size_bytes,
+            is_wordpress,
+            version,
+            user_exists,
+            user_privileges,
+            routine_count,
+            event_count,
+        )
+
+
+def inspect(connection: Connection, credentials: CredentialSource) -> ConnectionState:
+    """Whether this account can use this database, and if not, why."""
+    with operation("inspect", connection) as fields:
+        try:
+            resolved = _resolve(credentials)
+        except (
+            CredentialsUnobtainableError,
+            CredentialsAbsentError,
+            ConfigurationError,
+            MissingDependencyError,
+        ):
+            fields["state"] = str(ConnectionState.CREDENTIALS_UNOBTAINABLE)
+            return ConnectionState.CREDENTIALS_UNOBTAINABLE
+        from .errors import AuthPluginRefusedError
+
+        try:
+            session = open_connection(connection, resolved, database=connection.database)
+        except AuthPluginRefusedError:
+            state = ConnectionState.AUTH_PLUGIN_REFUSED
+        except Exception as exc:  # noqa: BLE001 - SSLError and driver errors both map here
+            state = classify(exc)
+        else:
+            session.close()
+            state = ConnectionState.READY
+        fields["state"] = str(state)
+        return state
+
+
+def schema_version(
+    connection: Connection, credentials: CredentialSource, table_prefix: str = "wp_"
+) -> SchemaVersion | None:
+    """The WordPress schema revision recorded in the options table."""
+    with operation("schema_version", connection):
+        resolved = _resolve(credentials)
+        session = _connect_or_raise(connection, resolved, connection.database)
+        try:
+            with session, session.cursor() as cur:
+                return _read_schema_version(cur, connection.database, table_prefix)
+        except pymysql.err.MySQLError as exc:
+            msg = f"could not read {table_prefix}options; is the table prefix correct?"
+            raise AccessDeniedError(msg) from exc