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

l3io/wp/database/credentials.py

@@ -0,0 +1,196 @@
+"""Database credentials and their sources.
+
+AD-9: resolution is an explicit call, never a property read. The original
+exposed ``username`` and ``password`` as property *getters* that performed an
+AWS round trip and mutated ``self`` -- hidden network I/O behind attribute
+access, with failures surfacing deep inside an unrelated database call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import structlog
+
+from .errors import (
+    CredentialsAbsentError,
+    CredentialsUnobtainableError,
+    InvalidArgumentsError,
+    MissingDependencyError,
+    RegionNotKnownError,
+)
+
+_log = structlog.get_logger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCredentials:
+    """A concrete username and password, and which source produced them.
+
+    The password is redacted in ``repr`` so it cannot reach a log line or a
+    traceback frame summary by accident.
+    """
+
+    username: str
+    password: str
+    source: str = "explicit"
+
+    def __repr__(self) -> str:
+        return (
+            f"ResolvedCredentials(username={self.username!r}, password='***', "
+            f"source={self.source!r})"
+        )
+
+
+@runtime_checkable
+class CredentialSource(Protocol):
+    """Anything that can produce credentials. Nothing needs to subclass a package type."""
+
+    @property
+    def source(self) -> str:
+        """A label for logs and errors. Never the secret."""
+        ...
+
+    def resolve(self) -> ResolvedCredentials:
+        """Obtain the credentials, performing I/O if the source requires it.
+
+        Raises:
+            CredentialsAbsentError: the source has nothing to offer.
+            CredentialsUnobtainableError: the source tried and failed.
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class Explicit:
+    """Credentials given directly."""
+
+    username: str
+    password: str
+
+    @property
+    def source(self) -> str:
+        return "explicit"
+
+    def resolve(self) -> ResolvedCredentials:
+        return ResolvedCredentials(self.username, self.password, self.source)
+
+    def __repr__(self) -> str:
+        return f"Explicit(username={self.username!r}, password='***')"
+
+
+@dataclass(frozen=True, slots=True)
+class Environment:
+    """Credentials held in two environment variables."""
+
+    username_var: str = "DB_USER"
+    password_var: str = "DB_PASSWORD"  # noqa: S105 - name of an environment variable, not a secret
+
+    @property
+    def source(self) -> str:
+        return f"environment:{self.username_var},{self.password_var}"
+
+    def resolve(self) -> ResolvedCredentials:
+        username = os.environ.get(self.username_var)
+        password = os.environ.get(self.password_var)
+        if username is None and password is None:
+            msg = f"neither {self.username_var} nor {self.password_var} is set"
+            raise CredentialsAbsentError(msg, sources=(self.source,))
+        if username is None or password is None:
+            unset = self.username_var if username is None else self.password_var
+            msg = f"{unset} is not set, although its partner variable is"
+            raise CredentialsUnobtainableError(msg)
+        return ResolvedCredentials(username, password, self.source)
+
+
+@dataclass(frozen=True, slots=True)
+class AwsSecretsManager:
+    """Credentials held in AWS Secrets Manager as JSON ``username``/``password``.
+
+    Needs the ``aws`` extra.
+    """
+
+    secret_id: str
+    region: str | None = None
+
+    @property
+    def source(self) -> str:
+        return f"aws-secrets-manager:{self.secret_id}"
+
+    def resolve(self) -> ResolvedCredentials:
+        # AD-8: the optional dependency is imported inside the function that uses it.
+        try:
+            import boto3
+        except ImportError as exc:
+            raise MissingDependencyError(extra="aws", distribution="boto3") from exc
+
+        # botocore's exceptions are not a public type (AD-14): everything that
+        # talks to AWS is in one block, and parsing what came back in another,
+        # so a client-side ValueError is never reported as a malformed secret.
+        try:
+            region = self.region or boto3.session.Session().region_name
+        except Exception as exc:  # noqa: BLE001 - botocore session errors (e.g. ProfileNotFound)
+            msg = f"could not read secret {self.secret_id!r}: the AWS session could not be set up"
+            raise CredentialsUnobtainableError(msg) from exc
+        if not region:
+            raise RegionNotKnownError
+
+        _log.debug("resolving secret", source=self.source, region=region)
+        try:
+            client = boto3.client("secretsmanager", region_name=region)
+            payload: Any = client.get_secret_value(SecretId=self.secret_id)["SecretString"]
+        except Exception as exc:  # noqa: BLE001 - boto3 errors are not a public type (AD-14)
+            msg = f"could not read secret {self.secret_id!r} from AWS Secrets Manager"
+            raise CredentialsUnobtainableError(msg) from exc
+
+        shape = (
+            f"secret {self.secret_id!r} is not shaped as expected: it must be a JSON "
+            "object whose 'username' and 'password' are strings"
+        )
+        try:
+            document = json.loads(payload)
+        except (TypeError, ValueError) as exc:
+            raise CredentialsUnobtainableError(shape) from exc
+        if not isinstance(document, dict):
+            raise CredentialsUnobtainableError(shape)
+        username, password = document.get("username"), document.get("password")
+        if not isinstance(username, str) or not isinstance(password, str):
+            raise CredentialsUnobtainableError(shape)
+        return ResolvedCredentials(username, password, self.source)
+
+
+class CredentialChain:
+    """The first source with an answer.
+
+    Moves to the next source only when one is *absent*. A source that *failed*
+    stops the chain, because falling through to a different credential after a
+    failure is a silent substitution.
+    """
+
+    __slots__ = ("_sources",)
+
+    def __init__(self, *sources: CredentialSource) -> None:
+        if not sources:
+            msg = "a CredentialChain needs at least one source"
+            raise InvalidArgumentsError(msg)
+        self._sources = sources
+
+    @property
+    def source(self) -> str:
+        return "chain(" + ", ".join(s.source for s in self._sources) + ")"
+
+    def resolve(self) -> ResolvedCredentials:
+        tried: list[str] = []
+        for candidate in self._sources:
+            try:
+                return candidate.resolve()
+            except CredentialsAbsentError:
+                tried.append(candidate.source)
+        msg = "no credential source had an answer: " + ", ".join(tried)
+        raise CredentialsAbsentError(msg, sources=tuple(tried))
+
+    def __repr__(self) -> str:
+        return f"CredentialChain({self.source})"

l3io/wp/database/encryption.py

@@ -0,0 +1,188 @@
+"""Optional age encryption of dumps (extra ``encryption``).
+
+Recipients / identities go through ``pyrage``. Passphrase streaming uses
+``l3io-age-passphrase`` (preferred) or stock ``age`` with
+``age-plugin-batchpass`` (see ``L3IO_AGE_PASSPHRASE_BACKEND``). The format is
+standard age, so any dump this package encrypts can be decrypted by the stock
+``age`` command line. Errors are mapped to package types: a wrong identity or
+passphrase is :class:`DecryptionError`; a damaged, truncated or non-age stream
+is :class:`CorruptDumpError` (probe V4). Secret identities and passphrases
+never appear in messages.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import IO, Any
+
+from . import _passphrase
+from .errors import CorruptDumpError, DecryptionError, InvalidArgumentsError, MissingDependencyError
+
+AGE_HEADER = b"age-encryption.org/v1"
+_SECRET_PREFIX = "AGE-SECRET-KEY-"  # noqa: S105 - the prefix age identities carry, not a secret
+
+
+def _pyrage() -> Any:
+    try:
+        import pyrage
+    except ImportError as exc:
+        raise MissingDependencyError(extra="encryption", distribution="pyrage") from exc
+    return pyrage
+
+
+def generate_identity() -> tuple[str, str]:
+    """A new age identity and its public recipient: ``(identity, recipient)``."""
+    pyrage = _pyrage()
+    identity = pyrage.x25519.Identity.generate()
+    return str(identity), str(identity.to_public())
+
+
+def read_identity(path: str | Path, passphrase: str | None = None) -> str:
+    """The age identity in a file, optionally passphrase-protected (age's own format)."""
+    pyrage = _pyrage()
+    try:
+        data = Path(path).read_bytes()
+    except OSError as exc:
+        msg = f"cannot read the identity file {str(path)!r}: {exc.strerror}"
+        raise InvalidArgumentsError(msg) from exc
+    if passphrase is not None:
+        try:
+            data = pyrage.passphrase.decrypt(data, passphrase)
+        except pyrage.DecryptError as exc:
+            msg = f"could not unlock the identity file {str(path)!r} with that passphrase"
+            raise DecryptionError(msg) from exc
+    for line in data.decode("utf-8", errors="replace").splitlines():
+        if line.strip().startswith(_SECRET_PREFIX):
+            return line.strip()
+    msg = f"{str(path)!r} holds no age identity"
+    raise InvalidArgumentsError(msg)
+
+
+def _recipients(pyrage: Any, recipients: Sequence[str]) -> list[Any]:
+    if not recipients:
+        msg = "encryption needs at least one recipient"
+        raise InvalidArgumentsError(msg)
+    parsed: list[Any] = []
+    for recipient in recipients:
+        try:
+            if recipient.startswith(("ssh-", "ecdsa-")):
+                parsed.append(pyrage.ssh.Recipient.from_str(recipient))
+            else:
+                parsed.append(pyrage.x25519.Recipient.from_str(recipient))
+        except Exception as exc:  # noqa: BLE001 - pyrage errors are not a public type (AD-14)
+            msg = f"not an age or SSH public key: {recipient[:12]}..."
+            raise InvalidArgumentsError(msg) from exc
+    return parsed
+
+
+def _identities(pyrage: Any, identities: Sequence[str]) -> list[Any]:
+    if not identities:
+        msg = "decryption needs at least one identity"
+        raise InvalidArgumentsError(msg)
+    parsed: list[Any] = []
+    for index, identity in enumerate(identities):
+        text = identity.strip()
+        try:
+            if text.startswith(_SECRET_PREFIX):
+                parsed.append(pyrage.x25519.Identity.from_str(text))
+            else:
+                parsed.append(pyrage.ssh.Identity.from_buffer(text.encode()))
+        except Exception as exc:  # noqa: BLE001 - pyrage errors are not a public type (AD-14)
+            msg = f"identity #{index + 1} is not a usable age or SSH private key"
+            raise InvalidArgumentsError(msg) from exc
+    return parsed
+
+
+def _mutex_secret(
+    named: str,
+    sequence: Sequence[str] | None,
+    passphrase: str | None,
+    *,
+    action: str,
+) -> None:
+    has_seq = sequence is not None
+    has_pass = passphrase is not None
+    if has_seq == has_pass:
+        if has_seq:
+            msg = f"supply {named}= or passphrase=, not both"
+        else:
+            msg = f"{action} needs {named}= or passphrase="
+        raise InvalidArgumentsError(msg)
+    if has_pass and passphrase == "":
+        msg = "passphrase must not be empty"
+        raise InvalidArgumentsError(msg)
+
+
+def check_recipients(recipients: Sequence[str]) -> None:
+    """Refuse recipients :func:`encrypt` could not use, before any data moves."""
+    _recipients(_pyrage(), recipients)
+
+
+def check_passphrase(passphrase: str) -> None:
+    """Refuse a passphrase :func:`encrypt` could not use, before any data moves."""
+    _passphrase.check_ready(passphrase)
+
+
+def encrypt(
+    reader: IO[bytes],
+    writer: IO[bytes],
+    recipients: Sequence[str] | None = None,
+    *,
+    passphrase: str | None = None,
+) -> None:
+    """Stream ``reader`` into ``writer`` as age.
+
+    Exactly one of ``recipients`` or ``passphrase``. Passphrase mode emits a
+    sole scrypt recipient (stock ``age -d``).
+    """
+    _mutex_secret("recipients", recipients, passphrase, action="encryption")
+    if passphrase is not None:
+        _passphrase.encrypt_io(reader, writer, passphrase)
+        return
+    pyrage = _pyrage()
+    try:
+        keys = _recipients(pyrage, recipients or ())
+        pyrage.encrypt_io(reader, writer, keys)
+    except pyrage.EncryptError as exc:
+        # pyrage flattens the caller's I/O exception into text, e.g. "OSError: [Errno 28] ..."
+        if str(exc).startswith("BrokenPipeError"):
+            raise BrokenPipeError(str(exc)) from exc
+        raise OSError(str(exc)) from exc
+
+
+def decrypt(
+    reader: IO[bytes],
+    writer: IO[bytes],
+    identities: Sequence[str] | None = None,
+    *,
+    passphrase: str | None = None,
+) -> None:
+    """Stream an age ``reader`` into ``writer`` as plaintext.
+
+    Exactly one of ``identities`` or ``passphrase``.
+    """
+    _mutex_secret("identities", identities, passphrase, action="decryption")
+    if passphrase is not None:
+        _passphrase.decrypt_io(reader, writer, passphrase)
+        return
+    pyrage = _pyrage()
+    try:
+        keys = _identities(pyrage, identities or ())
+        pyrage.decrypt_io(reader, writer, keys)
+    except BrokenPipeError:
+        raise  # the consumer stopped reading; not a property of the stream
+    except pyrage.DecryptError as exc:
+        text = str(exc)
+        if "No matching keys" in text:
+            msg = "none of the supplied identities can 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:
+        # pyrage's own stream failure is a bare OSError without errno; anything else is
+        # the caller's reader or writer failing and keeps its type and errno.
+        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

l3io/wp/database/errors.py

@@ -0,0 +1,186 @@
+"""Exception hierarchy owned by this package.
+
+AD-14: no dependency's exception type crosses a public boundary. Driver and SDK
+errors are caught and re-raised as one of these, with ``raise ... from``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .verdict import Verdict
+
+
+class DatabaseError(Exception):
+    """Base class for every error this package raises."""
+
+
+class InvalidArgumentsError(DatabaseError):
+    """An invalid combination of arguments was supplied."""
+
+
+class InvalidIdentifierError(DatabaseError):
+    """A database or user name is not usable as a MySQL identifier."""
+
+    def __init__(self, kind: str, value: str, reason: str) -> None:
+        self.kind = kind
+        self.value = value
+        self.reason = reason
+        super().__init__(f"{kind} {value!r} is not a valid identifier: {reason}")
+
+
+class InvalidDatabaseNameError(InvalidIdentifierError):
+    """A database name is not usable as a MySQL identifier."""
+
+    def __init__(self, value: str, reason: str = "not a valid database name") -> None:
+        super().__init__("database name", value, reason)
+
+
+class MissingDependencyError(DatabaseError):
+    """An optional feature was used without its extra installed.
+
+    AD-8: optional dependencies are imported inside the function that needs
+    them, and their absence is reported by naming the extra to install. A
+    version outside the extra's range is reported the same way, with ``found``
+    set to the installed version.
+    """
+
+    def __init__(
+        self,
+        extra: str,
+        distribution: str,
+        *,
+        found: str | None = None,
+        required: str | None = None,
+    ) -> None:
+        self.extra = extra
+        self.distribution = distribution
+        self.found = found
+        state = (
+            "which is not installed"
+            if found is None
+            else f"at {required}, and {found} is installed"
+        )
+        super().__init__(
+            f"this feature needs {distribution!r}, {state}. "
+            f"Install it with: pip install 'l3io-wordpress-database[{extra}]'"
+        )
+
+
+class CredentialsUnobtainableError(DatabaseError):
+    """Credentials could not be obtained from their source.
+
+    Distinct from authentication failure: nothing was attempted against the
+    database, because there was nothing to attempt it with.
+    """
+
+
+class CredentialsAbsentError(DatabaseError):
+    """A credential source had nothing to offer.
+
+    Distinct from :class:`CredentialsUnobtainableError`: an unset variable is
+    absence, a refused AWS call is failure. A
+    :class:`~l3io.wp.database.CredentialChain` moves on only after absence.
+    """
+
+    def __init__(self, message: str, sources: tuple[str, ...] = ()) -> None:
+        self.sources = sources
+        super().__init__(message)
+
+
+class RegionNotKnownError(CredentialsUnobtainableError):
+    """An AWS region was neither supplied nor discoverable from the session."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "the AWS region was not supplied and could not be determined from the current session"
+        )
+
+
+class ConfigurationError(DatabaseError):
+    """A WordPress configuration file could not be used."""
+
+
+class ConfigUnreadableError(ConfigurationError):
+    """The configuration file could not be read."""
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        super().__init__(f"could not read WordPress configuration {path!r}: {reason}")
+
+
+class MissingConfigValueError(ConfigurationError):
+    """A setting the database needs is not defined in the configuration."""
+
+    def __init__(self, key: str, path: str) -> None:
+        self.key = key
+        self.path = path
+        super().__init__(f"{key} is not defined in {path!r}")
+
+
+class DatabaseUnreachableError(DatabaseError):
+    """The database server could not be reached at all."""
+
+
+class TlsHandshakeError(DatabaseError):
+    """TLS was required but the server did not offer or complete a handshake."""
+
+
+class TlsVerificationError(DatabaseError):
+    """TLS was established but the server certificate did not verify."""
+
+
+class AuthenticationFailedError(DatabaseError):
+    """The server was reached but rejected the supplied credentials."""
+
+
+class AuthPluginRefusedError(DatabaseError):
+    """The server asked for an authentication plugin this package will not use.
+
+    ``plugin`` is the server-requested name. The message never includes the
+    password.
+    """
+
+    def __init__(self, plugin: str, message: str | None = None) -> None:
+        self.plugin = plugin
+        super().__init__(message or f"authentication plugin {plugin!r} is not allowed")
+
+
+class AccessDeniedError(DatabaseError):
+    """Authentication succeeded but the account may not use the database."""
+
+
+class ProvisioningError(DatabaseError):
+    """A provisioning operation started and failed part-way."""
+
+    def __init__(self, message: str, completed: tuple[str, ...] = ()) -> None:
+        self.completed = completed
+        super().__init__(message)
+
+
+class RefusedError(DatabaseError):
+    """A check found a blocker, so the operation did not run."""
+
+    def __init__(self, verdict: Verdict) -> None:
+        self.verdict = verdict
+        reasons = "; ".join(f"{f.code}: {f.message}" for f in verdict.blockers)
+        super().__init__(f"{verdict.operation} refused: {reasons}")
+
+
+class TransferError(DatabaseError):
+    """A dump or load started and failed. ``stderr`` is capped and redacted."""
+
+    def __init__(self, message: str, verdict: Verdict, exit_code: int | None, stderr: str) -> None:
+        self.verdict = verdict
+        self.exit_code = exit_code
+        self.stderr = stderr
+        super().__init__(message)
+
+
+class DecryptionError(DatabaseError):
+    """None of the supplied identities or the passphrase can decrypt the source."""
+
+
+class CorruptDumpError(DatabaseError):
+    """An encrypted source is truncated, damaged, or not an age file."""