Feat: credential and auth model (tokens, delagation)

docs/user/reference/api.md

@@ -19,6 +19,14 @@ Anything else, including every name starting with `_`, is internal.
 
 ::: intercede.registry
 
+## Credentials
+
+::: intercede.auth.models
+
+::: intercede.auth.protocols
+
+::: intercede.auth.providers
+
 ## Exceptions
 
 ::: intercede.exceptions

src/intercede/_backends/credentials.py

@@ -0,0 +1,192 @@
+"""What a backend asks its credential provider for, when, and what it accepts back.
+
+``credential_requirements`` turns a configuration into what to ask for. This is
+also the one place freshness is decided. A backend holds a ``CredentialCache``,
+and before each operation asks it for that operation's credential: the provider
+is asked only when there is none yet or it is about to expire. Where credentials
+come from, and how they are renewed, stays the consumer's business, inside its
+provider.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from intercede.auth.models import (
+    BearerToken,
+    Credential,
+    CredentialRequirements,
+    SSHPassword,
+    SSHPrivateKey,
+)
+from intercede.auth.protocols import CredentialProvider
+from intercede.config import (
+    ARCConfig,
+    BackendConfig,
+    BatchSSHConfig,
+    HTCondorCEConfig,
+)
+from intercede.exceptions import AuthenticationError, InterCEdeError
+
+# What each configured SSH auth mode asks the credential provider for.
+# "agent" is absent on purpose: an SSH agent holds the key, so nothing is asked.
+AUTH_KINDS: dict[str, type[Credential]] = {
+    "key": SSHPrivateKey,
+    "password": SSHPassword,
+}
+
+# Ask again this long before a credential expires, so it cannot run out in the
+# middle of an operation. A library default; whether a provider should be able
+# to change it is still open.
+DEFAULT_MARGIN = timedelta(minutes=5)
+
+
+def credential_requirements(
+    config: BackendConfig, scopes: frozenset[str] = frozenset()
+) -> CredentialRequirements | None:
+    """Say what a backend must ask its provider for.
+
+    Args:
+        config: The backend's validated configuration.
+        scopes: The scopes of the operation about to run, for token-based
+            backends; ignored by the others.
+
+    Returns:
+        What to ask for, or None when the backend needs no credential: it runs
+        on this host, or an SSH agent holds the key.
+    """
+    if isinstance(config, ARCConfig | HTCondorCEConfig):
+        # The endpoint is the resource, so a token is minted for this CE's audience.
+        return CredentialRequirements(
+            resource=config.endpoint,
+            kind=BearerToken,
+            scopes=scopes,
+        )
+    if isinstance(config, BatchSSHConfig) and config.auth != "agent":
+        # The resource is the login, ``user@host:port``: a provider finds the key
+        # or password by it, and the same host can take different users.
+        return CredentialRequirements(
+            resource=f"{config.user}@{config.host}:{config.port}",
+            kind=AUTH_KINDS[config.auth],
+        )
+    return None
+
+
+def is_stale(
+    credential: Credential | None,
+    requirements: CredentialRequirements,
+    *,
+    margin: timedelta = DEFAULT_MARGIN,
+    now: datetime | None = None,
+) -> bool:
+    """Tell whether ``credential`` cannot serve ``requirements`` for ``margin`` more.
+
+    A credential that never expires is never stale. Only the kind and the expiry
+    are checked, not the scopes, since a token is opaque to interCEde: ``credential``
+    must have been given for these same requirements, as ``CredentialCache`` ensures.
+
+    Args:
+        credential: The one the backend holds, or None before its first request.
+        requirements: What the backend needs for the operation about to run.
+        margin: How long the credential must stay valid from now.
+        now: The current time; tests pass a fixed one.
+
+    Returns:
+        True when there is no credential yet, when it is of another kind than
+        required, or when it expires within ``margin``.
+    """
+    if not isinstance(credential, requirements.kind):
+        return True
+    if credential.expires_at is None:
+        return False
+    return credential.expires_at - margin <= (now or datetime.now(UTC))
+
+
+async def refresh_if_stale(
+    current: Credential | None,
+    requirements: CredentialRequirements,
+    provider: CredentialProvider,
+    *,
+    margin: timedelta = DEFAULT_MARGIN,
+    now: datetime | None = None,
+) -> Credential:
+    """Return ``current`` while it is fresh, otherwise a new one from ``provider``.
+
+    Args:
+        current: The credential the backend holds, or None before its first request.
+        requirements: What the backend needs for the operation about to run.
+        provider: The consumer's provider, asked only when ``current`` is stale.
+        margin: How long the credential must stay valid from now.
+        now: The current time; tests pass a fixed one.
+
+    Returns:
+        The credential to authenticate with: ``current``, or the provider's new one.
+
+    Raises:
+        AuthenticationError: The provider failed, returned something other than
+            the required kind, or returned a credential that has already expired.
+            Always a failure of the whole operation, never a per-job outcome.
+    """
+    if not is_stale(current, requirements, margin=margin, now=now):
+        assert current is not None  # is_stale() is True for None
+        return current
+
+    try:
+        fresh = await provider.get(requirements)
+    except InterCEdeError:
+        raise  # already typed, e.g. an AuthenticationError from the provider
+    except Exception as exc:
+        # Only the type: the provider's message may hold a token or a secret URL.
+        # The exception itself stays available as __cause__.
+        raise AuthenticationError(
+            f"the credential provider failed for {requirements.resource} "
+            f"with {type(exc).__name__}"
+        ) from exc
+
+    if not isinstance(fresh, requirements.kind):
+        raise AuthenticationError(
+            f"the credential provider returned a {type(fresh).__name__} "
+            f"for {requirements.resource}, not a {requirements.kind.__name__}"
+        )
+    # Expiring within the margin is accepted (it is asked again next time);
+    # already expired is not, since it cannot authenticate anything.
+    if is_stale(fresh, requirements, margin=timedelta(0), now=now):
+        raise AuthenticationError(
+            f"the credential provider returned an expired credential "
+            f"for {requirements.resource}"
+        )
+    return fresh
+
+
+class CredentialCache:
+    """Keeps one credential per requirements for one backend, so each scope gets its own token.
+
+    The provider is asked again only when that credential is missing or about to expire.
+    """
+
+    def __init__(self, provider: CredentialProvider) -> None:
+        self._provider = provider
+        self._held: dict[CredentialRequirements, Credential] = {}
+
+    async def fresh(self, requirements: CredentialRequirements) -> Credential:
+        """Return the credential for these requirements, asking the provider if needed.
+
+        Args:
+            requirements: What the backend needs for the operation about to run.
+
+        Returns:
+            The credential to authenticate with.
+
+        Raises:
+            AuthenticationError: The provider failed, returned something other than
+                the required kind, or returned a credential that has already expired.
+        """
+        credential = await refresh_if_stale(
+            self._held.get(requirements), requirements, self._provider
+        )
+        self._held[requirements] = credential
+        return credential
+
+    def clear(self) -> None:
+        """Forget every credential, as a backend does when it closes."""
+        self._held.clear()

src/intercede/_backends/fake.py

@@ -13,6 +13,7 @@
 from typing import Self
 
 from intercede._backends.config import FakeConfig
+from intercede.auth.protocols import CredentialProvider
 from intercede.exceptions import (
     InterCEdeError,
     ResourceUnavailableError,
@@ -94,11 +95,15 @@ def __init__(
         self._closed = False
 
     @classmethod
-    def from_settings(cls, settings: FakeConfig) -> Self:
+    def from_settings(
+        cls, settings: FakeConfig, credentials: CredentialProvider
+    ) -> Self:
         """Build the fake from its settings; how the registry constructs it.
 
         Args:
             settings: The fake's settings: only the resource it reports.
+            credentials: Never asked: nothing leaves the process, so the fake
+                needs no credentials.
 
         Returns:
             A new fake, not yet opened.
@@ -379,4 +384,6 @@ def _write_job_files(
 _kill: type[Killable] = FakeBackend
 _purge: type[Purgeable] = FakeBackend
 _diag: type[Diagnosable] = FakeBackend
-_built_by_registry: Callable[[FakeConfig], JobBackend] = FakeBackend.from_settings
+_built_by_registry: Callable[[FakeConfig, CredentialProvider], JobBackend] = (
+    FakeBackend.from_settings
+)

src/intercede/auth/__init__.py

@@ -0,0 +1,28 @@
+"""Backend credentials: typed, declared, supplied by a provider.
+
+A consumer implements a ``CredentialProvider``, which returns the one credential
+a backend asks for. Configuration never holds a secret: it only says how a backend
+logs in, and the provider supplies the credential at run time.
+"""
+
+from __future__ import annotations
+
+from intercede.auth.models import (
+    BearerToken,
+    Credential,
+    CredentialRequirements,
+    SSHPassword,
+    SSHPrivateKey,
+)
+from intercede.auth.protocols import CredentialProvider
+from intercede.auth.providers import StaticCredentials
+
+__all__ = [
+    "BearerToken",
+    "Credential",
+    "CredentialProvider",
+    "CredentialRequirements",
+    "SSHPassword",
+    "SSHPrivateKey",
+    "StaticCredentials",
+]

src/intercede/auth/models.py

@@ -0,0 +1,106 @@
+"""The public credential models a consumer of interCEde can use.
+
+Credentials are immutable values. Secret material is held in pydantic's secret
+types, so a credential cannot be printed or logged by accident: ``repr``,
+``str`` and JSON all show ``**********``, and the content is only readable on
+purpose, with ``get_secret_value()``.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import (
+    AwareDatetime,
+    ConfigDict,
+    SecretBytes,
+    SecretStr,
+    model_validator,
+)
+
+from intercede.models import _Model
+
+__all__ = [
+    "BearerToken",
+    "Credential",
+    "CredentialRequirements",
+    "SSHPassword",
+    "SSHPrivateKey",
+]
+
+
+# --------------------------------------------------------------------------
+# Credential values
+# --------------------------------------------------------------------------
+
+
+class Credential(_Model):
+    """Base of every credential: the one field the freshness check needs.
+
+    Not used on its own: a provider returns one of the concrete kinds below.
+    """
+
+    # Added to _Model's settings: a value given by mistake may be the secret
+    # itself, so no error message repeats one.
+    model_config = ConfigDict(hide_input_in_errors=True, use_attribute_docstrings=True)
+
+    expires_at: AwareDatetime | None = None
+    """When the credential stops working, with a timezone, so it can be compared
+    with the current time. None means it never expires, as for SSH secrets."""
+
+
+class BearerToken(Credential):
+    """A token for the channel to a CE. Opaque to interCEde."""
+
+    value: SecretStr
+    """The token itself."""
+
+
+class SSHPrivateKey(Credential):
+    """An SSH private key: the key itself, never a path on some host."""
+
+    pem: SecretBytes
+    """The private key, PEM-encoded."""
+
+    passphrase: SecretStr | None = None
+    """The passphrase the key is encrypted with, or None if it is not."""
+
+
+class SSHPassword(Credential):
+    """A password for an SSH login."""
+
+    value: SecretStr
+    """The password itself."""
+
+
+# --------------------------------------------------------------------------
+# What a backend asks for
+# --------------------------------------------------------------------------
+
+
+class CredentialRequirements(_Model):
+    """What a backend asks its provider for.
+
+    The backend computes it from its own configuration and keeps it to itself:
+    a consumer only meets it as the argument to its provider's ``get``.
+    """
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    resource: str
+    """Which backend instance is asking: the endpoint it talks to, the same
+    string as ``JobHandle.resource``. For a token this is also the audience,
+    in the form that CE expects."""
+
+    kind: type[Credential]
+    """The kind of credential needed: a backend authenticates with exactly one."""
+
+    scopes: frozenset[str] = frozenset()
+    """For a token, the scopes of the operation about to run; empty for the
+    other kinds."""
+
+    @model_validator(mode="after")
+    def _concrete_kind(self) -> Self:
+        if self.kind is Credential:
+            raise ValueError("kind must be a concrete kind, not the Credential base")
+        return self