l3io-wordpress-backup 1.0.0__py3-none-any.whl

l3io/wp/backup/adapters/credential_providers.py

@@ -0,0 +1,236 @@
+"""FR-14/AD-9 — the credential chains, in the domain's declared precedence.
+
+Layer: ``adapters`` (AD-1). It imports ``domain/`` and ``adapters/redaction``;
+``l3io.wp.database`` (a required dependency, owner decision 76) is imported
+**inside the functions that use it** and, for annotations, under
+``TYPE_CHECKING`` (AD-8).
+
+Two builders put database's own sources in order and return a database
+``CredentialChain`` (first source with an answer wins; a source that *failed*
+stops the chain). They write no chain and no source of their own, call no
+``resolve()`` and do no I/O:
+
+- :func:`wordpress_credentials` — ``WORDPRESS_CREDENTIAL_PRECEDENCE``: the
+  spec (``Explicit`` or ``AwsSecretsManager``), then the environment
+  (:data:`WORDPRESS_USER_VAR`/:data:`WORDPRESS_PASSWORD_VAR`), then
+  ``wp-config.php``.
+- :func:`admin_credentials` — ``ADMIN_CREDENTIAL_PRECEDENCE``: the spec, then
+  the environment (:data:`ADMIN_USER_VAR`/:data:`ADMIN_PASSWORD_VAR`), and never
+  ``wp-config.php``. ``None`` when there is no administrator source at all.
+
+The environment step is included when either of its two variables is present
+in ``environ``; database's ``Environment`` then reads ``os.environ`` when the
+chain resolves, so the composition root passes ``os.environ``. A variable set
+to ``""`` counts as set, and a password shorter than
+``adapters/redaction.MIN_SECRET_LENGTH`` (the empty one included) is accepted
+with WARNING ``credential_below_redaction_floor``, logged by
+``adapters/database.py``'s wrapper when the chain resolves (owner decision 61,
+amending ADR-0018). The one built exception is
+``cli/credentials.py::admin_spec``'s ``--admin-password`` fallback, which
+reads an empty ``L3IO_WP_BACKUP_ADMIN_PASSWORD`` as unset. One
+variable of a pair set
+without its partner is a failure, never an absence, so it does not fall
+through to ``wp-config.php``.
+
+An explicit spec's password is registered with the Run's ``SecretRegistry``
+when its source is built, and a short one warned of there; every password the
+chain resolves is registered by ``adapters/database.py``'s wrapper, the only
+caller of these builders.
+
+One source is this module's own, and it provides nothing new:
+:func:`resolved_credentials` replays a ``ResolvedCredentialSpec``, the answer
+a WordPress chain gave a backup the CLI started as root, before it switched to
+the Site Root's owner (owner decision 67), under that chain's label.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Final, Literal
+
+import structlog
+
+from l3io.wp.backup.adapters.redaction import (
+    MIN_SECRET_LENGTH,
+    note_below_redaction_floor,
+)
+from l3io.wp.backup.domain.credentials import (
+    ADMIN_CREDENTIAL_PRECEDENCE,
+    WORDPRESS_CREDENTIAL_PRECEDENCE,
+    AwsSecretCredentialSpec,
+    CredentialOrigin,
+    CredentialSpec,
+    ResolvedCredentialSpec,
+)
+
+if TYPE_CHECKING:
+    from l3io.wp.database import CredentialSource, ResolvedCredentials
+
+    from l3io.wp.backup.adapters.redaction import SecretRegistry
+
+__all__ = [
+    "ADMIN_PASSWORD_VAR",
+    "ADMIN_USER_VAR",
+    "WORDPRESS_PASSWORD_VAR",
+    "WORDPRESS_USER_VAR",
+    "admin_credentials",
+    "resolved_credentials",
+    "unset_partner",
+    "wordpress_credentials",
+]
+
+_log = structlog.get_logger(__name__)
+
+#: The WordPress account's variables. Database's ``DB_USER``/``DB_PASSWORD``
+#: are deliberately not used: an unrelated tool may have set them.
+WORDPRESS_USER_VAR: Final[str] = "L3IO_WP_BACKUP_DB_USER"
+WORDPRESS_PASSWORD_VAR: Final[str] = "L3IO_WP_BACKUP_DB_PASSWORD"  # noqa: S105 - a name
+#: The administrator account's variables.
+ADMIN_USER_VAR: Final[str] = "L3IO_WP_BACKUP_ADMIN_USER"
+ADMIN_PASSWORD_VAR: Final[str] = "L3IO_WP_BACKUP_ADMIN_PASSWORD"  # noqa: S105 - a name
+
+_Role = Literal["wordpress", "administrator"]
+_PAIRS: Final[Mapping[_Role, tuple[str, str]]] = {
+    "wordpress": (WORDPRESS_USER_VAR, WORDPRESS_PASSWORD_VAR),
+    "administrator": (ADMIN_USER_VAR, ADMIN_PASSWORD_VAR),
+}
+
+
+def unset_partner(environ: Mapping[str, str], role: _Role) -> str | None:
+    """The unset variable of ``role``'s pair when only its partner is set."""
+    user, password = _PAIRS[role]
+    if (user in environ) == (password in environ):
+        return None
+    return password if user in environ else user
+
+
+def _explicit_step(
+    spec: CredentialSpec | None, secrets: SecretRegistry
+) -> CredentialSource | None:
+    if spec is None:
+        return None
+    from l3io.wp import database as wpdb
+
+    if isinstance(spec, AwsSecretCredentialSpec):
+        return wpdb.AwsSecretsManager(spec.secret_id, spec.region)
+    secrets.register(spec.secret, source="explicit")
+    if len(spec.secret) < MIN_SECRET_LENGTH:
+        # Owner decision 61 (amending ADR-0018): accepted, with a WARNING.
+        note_below_redaction_floor("explicit")
+    # Handed to l3io-wordpress-database: the one place it is revealed here.
+    return wpdb.Explicit(spec.username, spec.secret.reveal())
+
+
+def _environment_step(
+    environ: Mapping[str, str], role: _Role
+) -> CredentialSource | None:
+    user, password = _PAIRS[role]
+    if user not in environ and password not in environ:
+        return None
+    from l3io.wp import database as wpdb
+
+    return wpdb.Environment(user, password)
+
+
+def _ordered(
+    role: _Role,
+    precedence: tuple[CredentialOrigin, ...],
+    steps: Mapping[CredentialOrigin, CredentialSource | None],
+) -> tuple[CredentialSource, ...]:
+    """The present steps in ``precedence`` order, logged by label.
+
+    Every origin in ``precedence`` must have a step (``None`` for absent), so
+    an origin the domain adds without a builder step fails here, loudly.
+    """
+    ordered = tuple(s for s in (steps[o] for o in precedence) if s is not None)
+    sources = tuple(s.source for s in ordered)
+    if ordered:
+        _log.debug("credential_chain_built", role=role, sources=sources)
+    else:
+        _log.debug(
+            "credential_chain_built", role=role, sources=sources, none_configured=True
+        )
+    return ordered
+
+
+def wordpress_credentials(
+    spec: CredentialSpec | None,
+    *,
+    wp_config: CredentialSource,
+    environ: Mapping[str, str],
+    secrets: SecretRegistry,
+) -> CredentialSource:
+    """The WordPress account's chain; ``wp_config`` is always its last step."""
+    from l3io.wp import database as wpdb
+
+    ordered = _ordered(
+        "wordpress",
+        WORDPRESS_CREDENTIAL_PRECEDENCE,
+        {
+            CredentialOrigin.EXPLICIT: _explicit_step(spec, secrets),
+            CredentialOrigin.ENVIRONMENT: _environment_step(environ, "wordpress"),
+            CredentialOrigin.WP_CONFIG: wp_config,
+        },
+    )
+    return wpdb.CredentialChain(*ordered)
+
+
+def admin_credentials(
+    spec: CredentialSpec | None,
+    *,
+    environ: Mapping[str, str],
+    secrets: SecretRegistry,
+) -> CredentialSource | None:
+    """The administrator's chain, or ``None`` when no source is configured.
+
+    There is no ``wp-config.php`` step and no WordPress account step, for any
+    input (AD-29): a missing administrator is refused where one is needed.
+    """
+    ordered = _ordered(
+        "administrator",
+        ADMIN_CREDENTIAL_PRECEDENCE,
+        {
+            CredentialOrigin.EXPLICIT: _explicit_step(spec, secrets),
+            CredentialOrigin.ENVIRONMENT: _environment_step(environ, "administrator"),
+        },
+    )
+    if not ordered:
+        return None
+    from l3io.wp import database as wpdb
+
+    return wpdb.CredentialChain(*ordered)
+
+
+class _Resolved:
+    """A ``CredentialSource`` replaying a :class:`ResolvedCredentialSpec`."""
+
+    __slots__ = ("_spec",)
+
+    def __init__(self, spec: ResolvedCredentialSpec) -> None:
+        self._spec = spec
+
+    def __repr__(self) -> str:
+        return f"Resolved({self.source!r})"
+
+    @property
+    def source(self) -> str:
+        return self._spec.chain
+
+    def resolve(self) -> ResolvedCredentials:
+        from l3io.wp import database as wpdb
+
+        spec = self._spec
+        # Handed to l3io-wordpress-database: revealed here only.
+        return wpdb.ResolvedCredentials(
+            spec.username, spec.secret.reveal(), spec.source
+        )
+
+
+def resolved_credentials(spec: ResolvedCredentialSpec) -> CredentialSource:
+    """The source answering with ``spec`` under its chain's label (decision 67).
+
+    No I/O and no registration: the password was registered, and a short one
+    warned of, when the chain resolved it; the caller registers it with the
+    Run's registry.
+    """
+    return _Resolved(spec)

l3io/wp/backup/adapters/crypto.py

@@ -0,0 +1,237 @@
+"""ADR-0014/ADR-0024, AD-26 — the passphrase payload cipher, via ``l3io-wp-database``.
+
+:class:`PassphraseCipher` implements the ``PayloadCipher`` port by calling
+``l3io.wp.database.encryption``'s ``encrypt``/``decrypt`` with ``passphrase=``;
+no cipher, KDF or ``age`` code is written or imported here (ADR-0014). The
+database import is deferred (AD-8). Database, ``pyrage`` and the binder are
+required dependencies (owner decision 76), so an installation that lacks one,
+or that has neither the binder nor the ``age`` command line as a backend,
+raises ``IncompleteInstallError`` naming the missing distribution. It is the one
+``PayloadCipher`` in the package (BL-E004-042), and every composition root
+builds it through :func:`build_payload_cipher` (E004-S01-003).
+
+Database's errors are mapped into this package's hierarchy (AD-14) and kept
+distinct: a passphrase that cannot open the payload is
+:class:`PassphraseRejectedError`, a damaged, truncated or non-age stream is
+:class:`PayloadDamagedError`. Both are ``VERIFICATION_FAILED`` (Shawn,
+2026-11-03): ``age`` authenticates every chunk, so either means the payload
+could not be authenticated. A passphrase or backend database refuses as
+invalid is :class:`EncryptionConfigError` (``USAGE``). No message carries
+database's text, and none carries the passphrase.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from collections.abc import Mapping
+from typing import IO, Final, overload
+
+from l3io.wp.backup.adapters.preflight import has_relative_path_entry
+from l3io.wp.backup.adapters.redaction import SecretRegistry
+from l3io.wp.backup.domain.errors import (
+    IncompleteInstallError,
+    PassphraseRejectedError,
+    PayloadDamagedError,
+    UsageError,
+)
+from l3io.wp.backup.domain.preflight import ToolRequirement
+from l3io.wp.backup.domain.secret import Secret, as_secret
+
+__all__ = [
+    "EncryptionConfigError",
+    "PassphraseCipher",
+    "build_payload_cipher",
+    "passphrase_backend_requirements",
+    "selected_backend",
+]
+
+_DISTRIBUTION: Final = "l3io-wordpress-database"
+#: Database's backend switch (its README and ADR-0003).
+_BACKEND_ENV: Final = "L3IO_AGE_PASSPHRASE_BACKEND"
+_BINDER_MODULE: Final = "l3io_age_passphrase"
+#: ``age`` 1.3 is the first release that ships ``age-plugin-batchpass`` (FR-27).
+_AGE_MINIMUM: Final = (1, 3)
+_NEEDED_FOR: Final = "the encrypted payload (ENCRYPT, VERIFY)"
+_REGISTRY_SOURCE: Final = "passphrase"
+#: The encryption a :class:`PassphraseRejectedError` names (``scheme``).
+_SCHEME: Final = "age"
+
+
+class EncryptionConfigError(UsageError):
+    """Database refused the passphrase or its backend setting as invalid.
+
+    Database's ``InvalidArgumentsError`` from ``check_passphrase``: an empty
+    passphrase, an unrecognised ``L3IO_AGE_PASSPHRASE_BACKEND``, or the ``cli``
+    backend without ``age`` and ``age-plugin-batchpass`` on ``PATH``. The
+    message never carries database's text, which could echo the input.
+    ``relative_path`` is ``True`` for the ``PATH`` refusal; ``arguments``
+    names what is at fault (``PATH``, or the passphrase and the backend
+    variable).
+    """
+
+    def __init__(self, *, relative_path: bool = False) -> None:
+        self.relative_path = relative_path
+        if relative_path:
+            super().__init__(
+                "encryption cannot run: the age command-line backend would be "
+                "looked up through a PATH with an empty or relative entry, so a "
+                "planted age could receive the passphrase; remove those entries "
+                "or use the in-process backend",
+                arguments=("PATH",),
+            )
+            return
+        super().__init__(
+            "encryption cannot run: the passphrase is empty, or "
+            f"{_BACKEND_ENV} names a backend that is unknown or not installed",
+            arguments=("passphrase", _BACKEND_ENV),
+        )
+
+
+def passphrase_backend_requirements(
+    *, environ: Mapping[str, str], needed_for: str
+) -> tuple[ToolRequirement, ...]:
+    """The external tools database's passphrase backend needs (Gate E004 AG-8).
+
+    Restates database's documented selection (README, ADR-0003), because its
+    resolver is private: ``binder`` needs no binary; ``auto`` (or unset) needs
+    none when the ``l3io-age-passphrase`` binder is importable (detected with
+    ``find_spec``, never imported), else ``age`` >= 1.3 and
+    ``age-plugin-batchpass``, which ``cli`` always needs. An unrecognised value
+    needs nothing here: ``check()`` refuses it, in one place. Reads only
+    ``environ``. Replace with a call if database exports a backend query.
+    """
+    if selected_backend(environ) == "cli":
+        return (
+            ToolRequirement("age", _AGE_MINIMUM, needed_for),
+            ToolRequirement("age-plugin-batchpass", None, needed_for),
+        )
+    return ()
+
+
+def selected_backend(environ: Mapping[str, str]) -> str:
+    """Database's backend for ``environ``: ``cli``, ``binder`` or the raw value.
+
+    ``auto`` (or unset) resolves to ``binder`` when the binder is importable
+    and to ``cli`` when it is not; an unrecognised value is returned as given.
+    """
+    requested = environ.get(_BACKEND_ENV, "auto").strip().lower() or "auto"
+    if requested == "auto":
+        return "cli" if importlib.util.find_spec(_BINDER_MODULE) is None else "binder"
+    return requested
+
+
+class PassphraseCipher:
+    """``PayloadCipher`` over database's ``age`` passphrase streams."""
+
+    __slots__ = ("_passphrase",)
+
+    def __init__(self, passphrase: Secret | str) -> None:
+        self._passphrase = as_secret(passphrase)
+
+    def __repr__(self) -> str:
+        return "PassphraseCipher(passphrase=<redacted>)"
+
+    def required_tools(self) -> tuple[ToolRequirement, ...]:
+        """The backend's external tools, for the plan's ``extra_tools``."""
+        return passphrase_backend_requirements(
+            environ=os.environ, needed_for=_NEEDED_FOR
+        )
+
+    def check(self) -> None:
+        """Refuse before any write if the passphrase or its backend cannot run.
+
+        ``IncompleteInstallError`` when database, ``pyrage`` or a usable
+        backend is missing; ``EncryptionConfigError`` for an invalid
+        passphrase or backend setting. Also ``EncryptionConfigError`` when the
+        ``cli`` backend is selected (explicitly, or because the binder is
+        unavailable) and ``PATH`` has an empty or relative entry: database
+        resolves ``age`` through it and hands it the passphrase, while the
+        preflight ignores such entries (AR-3, RT-7).
+        """
+        if selected_backend(os.environ) == "cli" and has_relative_path_entry():
+            raise EncryptionConfigError(relative_path=True)
+        try:
+            from l3io.wp.database import encryption
+            from l3io.wp.database.errors import (
+                InvalidArgumentsError,
+                MissingDependencyError,
+            )
+        except ImportError as exc:
+            raise IncompleteInstallError(_DISTRIBUTION) from exc
+        try:
+            encryption.check_passphrase(self._passphrase.reveal())
+        except MissingDependencyError as exc:
+            raise IncompleteInstallError(exc.distribution) from exc
+        except InvalidArgumentsError as exc:
+            raise EncryptionConfigError from exc
+
+    def encrypt(self, reader: IO[bytes], writer: IO[bytes]) -> None:
+        """Stream ``reader`` into ``writer`` as ``age`` (a sole scrypt recipient)."""
+        try:
+            from l3io.wp.database import encryption
+            from l3io.wp.database.errors import (
+                InvalidArgumentsError,
+                MissingDependencyError,
+            )
+        except ImportError as exc:
+            raise IncompleteInstallError(_DISTRIBUTION) from exc
+        try:
+            encryption.encrypt(reader, writer, passphrase=self._passphrase.reveal())
+        except MissingDependencyError as exc:
+            raise IncompleteInstallError(exc.distribution) from exc
+        except InvalidArgumentsError as exc:
+            raise EncryptionConfigError from exc
+
+    def decrypt(self, reader: IO[bytes], writer: IO[bytes]) -> None:
+        """Stream ``age`` ciphertext into ``writer``, authenticating every chunk."""
+        try:
+            from l3io.wp.database import encryption
+            from l3io.wp.database.errors import (
+                CorruptDumpError,
+                DecryptionError,
+                InvalidArgumentsError,
+                MissingDependencyError,
+            )
+        except ImportError as exc:
+            raise IncompleteInstallError(_DISTRIBUTION) from exc
+        try:
+            encryption.decrypt(reader, writer, passphrase=self._passphrase.reveal())
+        except MissingDependencyError as exc:
+            raise IncompleteInstallError(exc.distribution) from exc
+        except InvalidArgumentsError as exc:
+            raise EncryptionConfigError from exc
+        except DecryptionError as exc:
+            raise PassphraseRejectedError(scheme=_SCHEME) from exc
+        except CorruptDumpError as exc:
+            raise PayloadDamagedError from exc
+
+
+@overload
+def build_payload_cipher(
+    *, passphrase: str | Secret, secrets: SecretRegistry
+) -> PassphraseCipher: ...
+@overload
+def build_payload_cipher(*, passphrase: None, secrets: SecretRegistry) -> None: ...
+@overload
+def build_payload_cipher(
+    *, passphrase: str | Secret | None, secrets: SecretRegistry
+) -> PassphraseCipher | None: ...
+def build_payload_cipher(
+    *, passphrase: str | Secret | None, secrets: SecretRegistry
+) -> PassphraseCipher | None:
+    """The one way a composition root turns a resolved passphrase into a cipher.
+
+    ``None`` for ``None``: whether a passphrase was required is the root's
+    call (``require_passphrase``, ``_require_cipher``, ``--authenticate``).
+    Otherwise the passphrase is registered for redaction (idempotent: the
+    AD-26 chain registered it already), and the cipher's ``check()`` runs
+    before it is returned, so every root refuses identically, Dry Run too.
+    """
+    if passphrase is None:
+        return None
+    secret = as_secret(passphrase)
+    secrets.register(secret, source=_REGISTRY_SOURCE)
+    cipher = PassphraseCipher(secret)
+    cipher.check()
+    return cipher