mainsequence 9.0.8.dev44__tar.gz → 9.0.8.dev45__tar.gz

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.8.dev44
+Version: 9.0.8.dev45
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence/cli/config.py

@@ -29,6 +29,7 @@ from keyring import core as keyring_core
 from keyring import errors as keyring_errors
 
 from mainsequence.defaults import CANONICAL_BACKEND_ENV, STANDARD_BACKEND_URL
+from mainsequence.runtime_credential_exchange import runtime_credential_configured
 
 APP_NAME = "MainSequenceCLI"
 
@@ -804,13 +805,8 @@ def session_report() -> dict:
     refresh_expires_at = token_expiry(refresh)
 
     if auth_mode == "runtime_credential":
-        authenticated = bool(
-            access
-            or (
-                (os.environ.get("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID") or "").strip()
-                and (os.environ.get("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET") or "").strip()
-            )
-        )
+        # The credential is an ID with a bootstrap secret or an identity token file.
+        authenticated = bool(access or runtime_credential_configured())
         session_expires_at = None
     elif refresh:
         authenticated = refresh_expires_at is None or refresh_expires_at > now

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence/client/utils.py

@@ -21,6 +21,14 @@ from requests.structures import CaseInsensitiveDict
 
 from mainsequence.defaults import resolve_backend_endpoint
 from mainsequence.logconf import logger
+from mainsequence.runtime_credential_exchange import (
+    RUNTIME_CREDENTIAL_ID_ENV,
+    RUNTIME_CREDENTIAL_SECRET_ENV,
+    RUNTIME_IDENTITY_TOKEN_FILE_ENV,
+    RuntimeIdentityTokenError,
+    exchange_runtime_credential,
+    identity_token_file_from_environment,
+)
 
 from ._transport import DEFAULT_ALLOWED_METHODS as DEFAULT_ALLOWED_METHODS
 from ._transport import DEFAULT_STATUS_FORCELIST as DEFAULT_STATUS_FORCELIST
@@ -309,6 +317,17 @@ class SessionJWTAuthProvider(BaseAuthProvider):
 
 @dataclass
 class RuntimeCredentialAuthProvider(BaseAuthProvider):
+    """
+    Exchange the runtime credential the platform injected for short-lived access tokens.
+
+    The proof is the projected workload identity token when
+    `MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE` is set: the file is read for every
+    exchange, and `MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET` is never read or sent.
+    Otherwise the proof is that bootstrap secret. The token is never kept on the
+    provider. Throttled (`429`) and temporarily unavailable (`503`) exchanges are
+    retried within the timeout budget; a rejected one (`401`) fails at once.
+    """
+
     credential_id: str | None = None
     credential_secret: str | None = None
     token_url: str | None = None
@@ -316,13 +335,18 @@ class RuntimeCredentialAuthProvider(BaseAuthProvider):
     refresh_skew_seconds: int = 30
     timeout: tuple[float, float] = DEFAULT_TIMEOUT
     expires_at: float | None = None
+    identity_token_file: str | None = None
     _lock: threading.RLock = field(default_factory=threading.RLock, init=False, repr=False)
 
     def __post_init__(self):
         if self.credential_id is None:
-            self.credential_id = os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID")
-        if self.credential_secret is None:
-            self.credential_secret = os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET")
+            self.credential_id = os.getenv(RUNTIME_CREDENTIAL_ID_ENV)
+        if self.identity_token_file is None:
+            self.identity_token_file = identity_token_file_from_environment()
+        else:
+            self.identity_token_file = str(self.identity_token_file).strip() or None
+        if self.credential_secret is None and not self.identity_token_file:
+            self.credential_secret = os.getenv(RUNTIME_CREDENTIAL_SECRET_ENV)
         if not self.token_url:
             self.token_url = f"{API_ENDPOINT}/runtime-credentials/token/"
 
@@ -344,20 +368,48 @@ class RuntimeCredentialAuthProvider(BaseAuthProvider):
 
         return exp <= int(time.time()) + self.refresh_skew_seconds
 
-    def _require_credentials(self) -> tuple[str, str]:
+    @staticmethod
+    def _log_exchange_retry(status: int, delay: float) -> None:
+        logger.warning(f"Runtime credential exchange returned {status}; retrying in {delay:.1f} s.")
+
+    def _exchange(self) -> requests.Response:
         credential_id = (self.credential_id or "").strip()
-        credential_secret = (self.credential_secret or "").strip()
+        identity_token_file = self.identity_token_file
+        credential_secret = None if identity_token_file else (self.credential_secret or "").strip()
         if not credential_id:
             raise AuthError(
                 "MAINSEQUENCE_RUNTIME_CREDENTIAL_ID is required when "
                 "MAINSEQUENCE_AUTH_MODE=runtime_credential."
             )
-        if not credential_secret:
+        if not identity_token_file and not credential_secret:
             raise AuthError(
                 "MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET is required when "
-                "MAINSEQUENCE_AUTH_MODE=runtime_credential."
+                "MAINSEQUENCE_AUTH_MODE=runtime_credential and "
+                f"{RUNTIME_IDENTITY_TOKEN_FILE_ENV} is not set."
             )
-        return credential_id, credential_secret
+        try:
+            # One budget for every attempt and wait, inside the caller's budget if any.
+            with request_budget(self.timeout) as budget:
+
+                def post(body: dict[str, str]) -> requests.Response:
+                    return requests.post(
+                        self.token_url,
+                        json=body,
+                        headers={"Content-Type": "application/json"},
+                        timeout=budget.timeout(),
+                        allow_redirects=False,
+                    )
+
+                return exchange_runtime_credential(
+                    post,
+                    credential_id=credential_id,
+                    credential_secret=credential_secret,
+                    identity_token_file=identity_token_file,
+                    deadline=budget.deadline,
+                    on_retry=self._log_exchange_retry,
+                )
+        except RuntimeIdentityTokenError as exc:
+            raise AuthError(str(exc)) from None
 
     def refresh(
         self,
@@ -370,17 +422,7 @@ class RuntimeCredentialAuthProvider(BaseAuthProvider):
             if not force and not self._needs_exchange():
                 return
 
-            credential_id, credential_secret = self._require_credentials()
-            response = requests.post(
-                self.token_url,
-                json={
-                    "credential_id": credential_id,
-                    "credential_secret": credential_secret,
-                },
-                headers={"Content-Type": "application/json"},
-                timeout=remaining_timeout(self.timeout),
-                allow_redirects=False,
-            )
+            response = self._exchange()
             if response.status_code < 200 or response.status_code >= 300:
                 raise AuthError(
                     f"Runtime credential exchange failed with status {response.status_code}."

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence/code_repository_context.py

@@ -10,6 +10,8 @@ from dataclasses import dataclass, replace
 from typing import Any, Literal
 from urllib.parse import urlsplit
 
+from mainsequence.runtime_credential_exchange import runtime_credential_configured
+
 CodeRepositoryContextStatus = Literal[
     "resolved",
     "code_repository_branch_not_registered",
@@ -204,9 +206,7 @@ def _exchange_authenticated_runtime_context_if_configured() -> None:
         return
     if (os.getenv("MAINSEQUENCE_AUTH_MODE") or "").strip().lower() != "runtime_credential":
         return
-    if not (os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID") or "").strip():
-        return
-    if not (os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET") or "").strip():
+    if not runtime_credential_configured():
         return
 
     from mainsequence.client.utils import AuthError, loaders

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence/logconf.py

@@ -5,6 +5,7 @@ import logging
 import logging.config
 import os
 import sys
+import time
 import traceback
 from collections.abc import Mapping
 from importlib.metadata import PackageNotFoundError
@@ -22,6 +23,13 @@ from structlog.stdlib import BoundLogger
 from .defaults import resolve_backend_endpoint
 from .instrumentation import OTelJSONRenderer
 from .repository_identity_security import UNSUPPORTED_SOURCE_IDENTITY_ENV_NAMES
+from .runtime_credential_exchange import (
+    RUNTIME_CREDENTIAL_ID_ENV,
+    RUNTIME_CREDENTIAL_SECRET_ENV,
+    exchange_runtime_credential,
+    identity_token_file_from_environment,
+    runtime_credential_configured,
+)
 from .runtime_flags import is_running_in_pod
 
 logger = None
@@ -94,20 +102,31 @@ def _request_job_startup_state(*, timeout_s: float = 10.0) -> dict[str, Any]:
         return headers, False
 
     def _exchange_runtime_credential() -> bool:
-        credential_id = (os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID") or "").strip()
-        credential_secret = (os.getenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET") or "").strip()
-        if not credential_id or not credential_secret:
+        if not runtime_credential_configured():
             return False
+        identity_token_file = identity_token_file_from_environment()
+        token_url = f"{_backend_base_url()}/api/v1/runtime-credentials/token/"
 
-        try:
-            token_resp = requests.post(
-                f"{_backend_base_url()}/api/v1/runtime-credentials/token/",
+        def _post(body: dict[str, str]) -> requests.Response:
+            return requests.post(
+                token_url,
                 headers={"Content-Type": "application/json"},
-                json={
-                    "credential_id": credential_id,
-                    "credential_secret": credential_secret,
-                },
+                json=body,
                 timeout=timeout_s,
+                allow_redirects=False,
+            )
+
+        try:
+            token_resp = exchange_runtime_credential(
+                _post,
+                credential_id=(os.getenv(RUNTIME_CREDENTIAL_ID_ENV) or "").strip(),
+                credential_secret=(
+                    None
+                    if identity_token_file
+                    else (os.getenv(RUNTIME_CREDENTIAL_SECRET_ENV) or "").strip()
+                ),
+                identity_token_file=identity_token_file,
+                deadline=time.monotonic() + timeout_s,
             )
         except Exception:
             return False

mainsequence-9.0.8.dev45/mainsequence/runtime_credential_exchange.py

@@ -0,0 +1,168 @@
+"""
+The runtime credential exchange, shared by the auth provider and the logger.
+
+A runtime started with ``MAINSEQUENCE_AUTH_MODE=runtime_credential`` exchanges its
+credential at ``POST /api/v1/runtime-credentials/token/`` for a short-lived access
+token. The request carries ``credential_id`` and exactly one proof:
+
+* ``workload_identity_token`` when ``MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE`` is
+  set: the projected token read from that file for every exchange, because the
+  file is rotated. The bootstrap secret is then never read or sent, and a missing,
+  unreadable or empty file is an error, never a fallback to the secret.
+* ``credential_secret`` otherwise: ``MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET``.
+
+The token exists only inside one exchange request. It is not kept on any object,
+written to the environment or a file, logged, or included in an error message.
+
+The logger exchanges a runtime credential while it is being configured, so this
+module imports nothing from the SDK.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+from typing import Any
+
+from urllib3.exceptions import InvalidHeader
+from urllib3.util import Retry
+
+RUNTIME_CREDENTIAL_ID_ENV = "MAINSEQUENCE_RUNTIME_CREDENTIAL_ID"
+RUNTIME_CREDENTIAL_SECRET_ENV = "MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET"
+RUNTIME_IDENTITY_TOKEN_FILE_ENV = "MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE"
+
+# 429: the exchange is throttled. 503: verification is temporarily unavailable.
+# Neither exchanged anything, so the same request may be sent again.
+RETRYABLE_EXCHANGE_STATUSES = frozenset({429, 503})
+EXCHANGE_RETRIES = 3
+EXCHANGE_BACKOFF_FACTOR = 0.5
+
+_RETRY_AFTER = Retry(total=0)
+
+
+class RuntimeIdentityTokenError(Exception):
+    """The runtime identity token file cannot be used. The message never holds its content."""
+
+
+def _environment_value(name: str) -> str:
+    return (os.getenv(name) or "").strip()
+
+
+def identity_token_file_from_environment() -> str | None:
+    """Return the path in ``MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE``, or None when unset."""
+    return _environment_value(RUNTIME_IDENTITY_TOKEN_FILE_ENV) or None
+
+
+def runtime_credential_configured() -> bool:
+    """
+    Say whether the environment holds a runtime credential to exchange.
+
+    That is a credential ID and one proof: the identity token file, or else the
+    bootstrap secret. Only the presence of the setting is checked. The token file
+    is read by the exchange itself, which reports a missing or empty file.
+    """
+    if not _environment_value(RUNTIME_CREDENTIAL_ID_ENV):
+        return False
+    if identity_token_file_from_environment():
+        return True
+    return bool(_environment_value(RUNTIME_CREDENTIAL_SECRET_ENV))
+
+
+def _read_identity_token(path: str) -> str:
+    source = f"The runtime identity token file {path} ({RUNTIME_IDENTITY_TOKEN_FILE_ENV})"
+    try:
+        with open(path, "rb") as token_file:
+            raw = token_file.read()
+    except FileNotFoundError:
+        raise RuntimeIdentityTokenError(f"{source} does not exist.") from None
+    except OSError as exc:
+        raise RuntimeIdentityTokenError(
+            f"{source} could not be read ({type(exc).__name__})."
+        ) from None
+    try:
+        token = raw.decode("utf-8").strip()
+    except UnicodeDecodeError:
+        # Raised below, outside this handler: the decode error holds the bytes.
+        token = None
+    if token is None:
+        raise RuntimeIdentityTokenError(f"{source} does not hold a token.")
+    if not token:
+        raise RuntimeIdentityTokenError(f"{source} is empty.")
+    return token
+
+
+def _request_body(
+    credential_id: str,
+    credential_secret: str | None,
+    identity_token_file: str | None,
+) -> dict[str, str]:
+    if identity_token_file:
+        return {
+            "credential_id": credential_id,
+            "workload_identity_token": _read_identity_token(identity_token_file),
+        }
+    return {"credential_id": credential_id, "credential_secret": credential_secret or ""}
+
+
+def _retry_delay(response: Any, attempt: int) -> float:
+    delay = min(EXCHANGE_BACKOFF_FACTOR * 2**attempt, Retry.DEFAULT_BACKOFF_MAX)
+    retry_after = (getattr(response, "headers", None) or {}).get("Retry-After")
+    if retry_after is not None:
+        try:
+            delay = max(delay, _RETRY_AFTER.parse_retry_after(str(retry_after)))
+        except InvalidHeader:
+            pass
+    return delay
+
+
+def exchange_runtime_credential(
+    send: Callable[[dict[str, str]], Any],
+    *,
+    credential_id: str,
+    credential_secret: str | None,
+    identity_token_file: str | None,
+    deadline: float,
+    on_retry: Callable[[int, float], None] | None = None,
+) -> Any:
+    """
+    Send one runtime credential exchange and return the last response.
+
+    Parameters
+    ----------
+    send:
+        Posts the JSON body it is given to the exchange route and returns the
+        response. It is called once per attempt.
+    credential_id:
+        The runtime credential ID.
+    credential_secret:
+        The bootstrap secret. Ignored when ``identity_token_file`` is set.
+    identity_token_file:
+        The projected token file. It is read again for every attempt.
+    deadline:
+        ``time.monotonic()`` value after which no retry starts.
+    on_retry:
+        Called with the status and the delay before each retry.
+
+    A ``429`` or ``503`` answer is retried up to ``EXCHANGE_RETRIES`` times. The
+    wait is the exponential backoff or the answer's ``Retry-After``, whichever is
+    longer; a wait that would not end before ``deadline`` ends the retries. Any
+    other answer, ``401`` included, is returned at once and the proof is never
+    switched. ``RuntimeIdentityTokenError`` is raised when the token file cannot
+    be used.
+    """
+    for attempt in range(EXCHANGE_RETRIES + 1):
+        response = send(_request_body(credential_id, credential_secret, identity_token_file))
+        status = response.status_code
+        if status not in RETRYABLE_EXCHANGE_STATUSES or attempt == EXCHANGE_RETRIES:
+            return response
+        delay = _retry_delay(response, attempt)
+        if delay >= deadline - time.monotonic():
+            return response
+        if on_retry is not None:
+            on_retry(status, delay)
+        close = getattr(response, "close", None)
+        if callable(close):
+            close()
+        time.sleep(delay)
+    raise AssertionError("Unreachable retry state")

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.8.dev44
+Version: 9.0.8.dev45
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/mainsequence.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ mainsequence/code_repository_skills.py
 mainsequence/defaults.py
 mainsequence/logconf.py
 mainsequence/repository_identity_security.py
+mainsequence/runtime_credential_exchange.py
 mainsequence/runtime_flags.py
 mainsequence/scaffold_skills.py
 mainsequence.egg-info/PKG-INFO
@@ -90,6 +91,7 @@ tests/test_logconf.py
 tests/test_models_user_request_bound_auth.py
 tests/test_notification_uid_contract.py
 tests/test_observability_client.py
+tests/test_runtime_credential_exchange.py
 tests/test_scaffold_skills.py
 tests/test_secret_client_model.py
 tests/test_source_ownership.py

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "9.0.8.dev44"
+version = "9.0.8.dev45"
 description = "Main Sequence SDK"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/tests/test_auth_precedence.py

@@ -150,6 +150,7 @@ def test_logconf_runtime_credential_exchanges_before_startup_state_request(monke
                 "credential_secret": "cred-secret",
             },
             "timeout": 10.0,
+            "allow_redirects": False,
         }
     ]
     assert os.environ["MAINSEQUENCE_ACCESS_TOKEN"] == "runtime-access"

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/tests/test_cli_secure_storage.py

@@ -1021,3 +1021,20 @@ def test_session_report_for_a_runtime_credential_has_no_session_expiry(monkeypat
     assert report["session_expires_at"] is None
     assert report["auth_mode"] == "runtime_credential"
     assert "cred-secret" not in json.dumps(report)
+
+
+def test_session_report_accepts_a_runtime_identity_token_file(monkeypatch, tmp_path):
+    _isolate_auth(monkeypatch, tmp_path, None)
+    monkeypatch.setattr(config, "auth_persistence_label", lambda: "test store")
+    token_file = tmp_path / "token"
+    token_file.write_text("projected-token", encoding="utf-8")
+    monkeypatch.setenv("MAINSEQUENCE_AUTH_MODE", "runtime_credential")
+    monkeypatch.setenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID", "cred-id")
+    monkeypatch.delenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET", raising=False)
+    monkeypatch.setenv("MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE", str(token_file))
+
+    report = config.session_report()
+
+    assert report["authenticated"] is True
+    assert report["session_expires_at"] is None
+    assert "projected-token" not in json.dumps(report)

{mainsequence-9.0.8.dev44 → mainsequence-9.0.8.dev45}/tests/test_code_repository_runtime_context.py

@@ -368,10 +368,21 @@ def test_authenticated_runtime_context_detects_git_drift(monkeypatch):
         code_repository_context.validate_code_repository_source_context(context=context)
 
 
-def test_configured_runtime_credential_exchanges_context_before_resolution(monkeypatch):
+@pytest.mark.parametrize(
+    ("proof_variable", "proof_value"),
+    [
+        ("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET", "credential-secret"),
+        ("MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE", "/var/run/secrets/runtime-identity/token"),
+    ],
+)
+def test_configured_runtime_credential_exchanges_context_before_resolution(
+    monkeypatch, proof_variable, proof_value
+):
     monkeypatch.setenv("MAINSEQUENCE_AUTH_MODE", "runtime_credential")
     monkeypatch.setenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID", "credential-id")
-    monkeypatch.setenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET", "credential-secret")
+    monkeypatch.delenv("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET", raising=False)
+    monkeypatch.delenv("MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE", raising=False)
+    monkeypatch.setenv(proof_variable, proof_value)
     events = []
     monkeypatch.setattr(
         code_repository_context,

mainsequence-9.0.8.dev45/tests/test_runtime_credential_exchange.py

@@ -0,0 +1,383 @@
+"""Runtime credential exchange: the projected identity token, the secret, and retries."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import time
+
+import pytest
+import requests
+from requests.structures import CaseInsensitiveDict
+
+from tests._support import load_sdk_submodule
+
+pytestmark = pytest.mark.usefixtures("isolated_sdk_imports", "clean_runtime_context_environment")
+
+TOKEN_URL = "https://backend.example/api/v1/runtime-credentials/token/"
+ID_ENV = "MAINSEQUENCE_RUNTIME_CREDENTIAL_ID"
+SECRET_ENV = "MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET"
+TOKEN_FILE_ENV = "MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE"
+SECRET = "bootstrap-secret-that-must-not-be-sent"
+JOB_RUN_UID = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
+
+
+class _Answer:
+    def __init__(self, status_code=200, payload=None, headers=None):
+        self.status_code = status_code
+        self._payload = payload if payload is not None else {}
+        self.headers = CaseInsensitiveDict(headers or {})
+        self.closed = False
+
+    def json(self):
+        return self._payload
+
+    def close(self):
+        self.closed = True
+
+
+def _granted(access="runtime-access"):
+    return _Answer(200, {"access": access, "token_type": "Bearer", "expires_in": 900})
+
+
+class _Exchange:
+    """Answer exchange requests from a script, and record them and every wait."""
+
+    def __init__(self, monkeypatch, *answers):
+        self.answers = list(answers)
+        self.requests = []
+        self.sleeps = []
+        monkeypatch.setattr(requests, "post", self._post)
+        monkeypatch.setattr(time, "sleep", self.sleeps.append)
+
+    def _post(self, url, **kwargs):
+        self.requests.append({"url": url, **kwargs})
+        if not self.answers:
+            raise AssertionError("unexpected runtime credential exchange request")
+        return self.answers.pop(0)
+
+    @property
+    def bodies(self):
+        return [request["json"] for request in self.requests]
+
+
+@pytest.fixture
+def runtime(monkeypatch, tmp_path):
+    for name in (
+        "MAINSEQUENCE_ACCESS_TOKEN",
+        "MAINSEQUENCE_REFRESH_TOKEN",
+        "JOB_RUN_UID",
+        SECRET_ENV,
+        TOKEN_FILE_ENV,
+    ):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("MAINSEQUENCE_AUTH_MODE", "runtime_credential")
+    monkeypatch.setenv("MAINSEQUENCE_ENDPOINT", "https://backend.example")
+    monkeypatch.setenv(ID_ENV, "cred-id")
+    return tmp_path
+
+
+def _use_token_file(monkeypatch, directory, token="projected-token-1"):
+    path = directory / "token"
+    path.write_text(token, encoding="utf-8")
+    monkeypatch.setenv(TOKEN_FILE_ENV, str(path))
+    return path
+
+
+@pytest.mark.parametrize("mode", ["identity_token", "bootstrap_secret"])
+def test_each_mode_sends_the_credential_id_and_exactly_one_proof(monkeypatch, runtime, mode):
+    if mode == "identity_token":
+        _use_token_file(monkeypatch, runtime)
+        monkeypatch.setenv(SECRET_ENV, SECRET)
+        proof = {"workload_identity_token": "projected-token-1"}
+    else:
+        monkeypatch.setenv(SECRET_ENV, "cred-secret")
+        proof = {"credential_secret": "cred-secret"}
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(monkeypatch, _granted())
+
+    headers = utils.RuntimeCredentialAuthProvider().get_headers()
+
+    assert headers["Authorization"] == "Bearer runtime-access"
+    assert exchange.bodies == [{"credential_id": "cred-id", **proof}]
+    assert exchange.requests[0]["url"] == TOKEN_URL
+    assert exchange.requests[0]["headers"] == {"Content-Type": "application/json"}
+    assert exchange.requests[0]["allow_redirects"] is False
+    assert os.environ["MAINSEQUENCE_ACCESS_TOKEN"] == "runtime-access"
+
+
+def test_identity_token_mode_never_reads_the_secret(monkeypatch, runtime):
+    _use_token_file(monkeypatch, runtime)
+    monkeypatch.setenv(SECRET_ENV, SECRET)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(monkeypatch, _granted())
+    read = []
+    getenv = os.getenv
+    monkeypatch.setattr(
+        os, "getenv", lambda name, default=None: read.append(name) or getenv(name, default)
+    )
+
+    provider = utils.RuntimeCredentialAuthProvider()
+    provider.refresh(force=True)
+
+    assert TOKEN_FILE_ENV in read
+    assert SECRET_ENV not in read
+    assert provider.credential_secret is None
+    assert SECRET not in repr(exchange.requests)
+
+
+def test_identity_token_file_is_read_for_every_exchange_and_not_at_start_up(monkeypatch, runtime):
+    token_file = runtime / "token"
+    monkeypatch.setenv(TOKEN_FILE_ENV, str(token_file))
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(monkeypatch, _granted("access-1"), _granted("access-2"))
+
+    provider = utils.RuntimeCredentialAuthProvider()
+    token_file.write_text("projected-token-1", encoding="utf-8")
+    provider.refresh(force=True)
+    token_file.write_text("projected-token-2", encoding="utf-8")
+    provider.refresh(force=True)
+
+    assert [body["workload_identity_token"] for body in exchange.bodies] == [
+        "projected-token-1",
+        "projected-token-2",
+    ]
+    assert os.environ["MAINSEQUENCE_ACCESS_TOKEN"] == "access-2"
+    assert "projected-token" not in repr(provider)
+
+
+@pytest.mark.parametrize(
+    ("prepare", "reason"),
+    [
+        (lambda path: None, "does not exist"),
+        (lambda path: path.write_text("", encoding="utf-8"), "is empty"),
+        (lambda path: path.write_text(" \n", encoding="utf-8"), "is empty"),
+        (lambda path: path.mkdir(), "could not be read (IsADirectoryError)"),
+        (lambda path: path.write_bytes(b"\xff\xfeprojected"), "does not hold a token"),
+    ],
+    ids=["missing", "empty", "blank", "unreadable", "not-text"],
+)
+def test_unusable_identity_token_file_fails_without_falling_back_to_the_secret(
+    monkeypatch, runtime, prepare, reason
+):
+    token_file = runtime / "token"
+    prepare(token_file)
+    monkeypatch.setenv(TOKEN_FILE_ENV, str(token_file))
+    monkeypatch.setenv(SECRET_ENV, SECRET)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(monkeypatch)
+
+    with pytest.raises(utils.AuthError) as raised:
+        utils.RuntimeCredentialAuthProvider().get_headers()
+
+    message = str(raised.value)
+    assert reason in message
+    assert str(token_file) in message
+    assert TOKEN_FILE_ENV in message
+    assert SECRET not in message
+    assert exchange.requests == []
+    chained = raised.value.__context__
+    while chained is not None:
+        assert not isinstance(chained, UnicodeDecodeError)
+        chained = chained.__context__
+
+
+@pytest.mark.parametrize("mode", ["identity_token", "bootstrap_secret"])
+@pytest.mark.parametrize("status", [429, 503])
+def test_throttled_or_unavailable_exchange_is_retried_honoring_retry_after(
+    monkeypatch, runtime, status, mode
+):
+    if mode == "identity_token":
+        _use_token_file(monkeypatch, runtime)
+        proof = {"workload_identity_token": "projected-token-1"}
+    else:
+        monkeypatch.setenv(SECRET_ENV, "cred-secret")
+        proof = {"credential_secret": "cred-secret"}
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    first = _Answer(status, {"detail": "Try again later."}, {"Retry-After": "7"})
+    exchange = _Exchange(monkeypatch, first, _Answer(status), _granted())
+
+    utils.RuntimeCredentialAuthProvider().refresh(force=True)
+
+    # Retry-After (7 s) is longer than the first backoff (0.5 s); the second answer
+    # has none, so the second backoff (1 s) applies.
+    assert exchange.sleeps == [7, 1]
+    assert exchange.bodies == [{"credential_id": "cred-id", **proof}] * 3
+    assert first.closed is True
+    assert os.environ["MAINSEQUENCE_ACCESS_TOKEN"] == "runtime-access"
+
+
+def test_exchange_retries_are_bounded(monkeypatch, runtime):
+    _use_token_file(monkeypatch, runtime)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(
+        monkeypatch, *(_Answer(503, headers={"Retry-After": "1"}) for _ in range(8))
+    )
+
+    with pytest.raises(utils.AuthError, match="failed with status 503"):
+        utils.RuntimeCredentialAuthProvider().refresh(force=True)
+
+    assert len(exchange.requests) == 4
+    assert exchange.sleeps == [1, 1, 2]
+
+
+def test_each_attempt_receives_only_the_remaining_budget(monkeypatch, runtime):
+    _use_token_file(monkeypatch, runtime)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    transport = importlib.import_module("mainsequence.client._transport")
+    exchange = _Exchange(monkeypatch, _Answer(503, headers={"Retry-After": "4"}), _granted())
+    now = [100.0]
+
+    def _sleep(delay):
+        exchange.sleeps.append(delay)
+        now[0] += delay
+
+    monkeypatch.setattr(time, "monotonic", lambda: now[0])
+    monkeypatch.setattr(time, "sleep", _sleep)
+
+    with transport.request_budget(10):
+        utils.RuntimeCredentialAuthProvider().refresh(force=True)
+
+    assert exchange.sleeps == [4]
+    assert [request["timeout"].total for request in exchange.requests] == [10, 6]
+
+
+def test_retry_after_beyond_the_timeout_budget_ends_the_retries(monkeypatch, runtime):
+    _use_token_file(monkeypatch, runtime)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    exchange = _Exchange(monkeypatch, _Answer(429, headers={"Retry-After": "3600"}))
+
+    with pytest.raises(utils.AuthError, match="failed with status 429"):
+        utils.RuntimeCredentialAuthProvider().refresh(force=True)
+
+    assert len(exchange.requests) == 1
+    assert exchange.sleeps == []
+
+
+@pytest.mark.parametrize("mode", ["identity_token", "bootstrap_secret"])
+def test_rejected_exchange_fails_at_once_without_switching_proof(monkeypatch, runtime, mode):
+    if mode == "identity_token":
+        _use_token_file(monkeypatch, runtime)
+        proof = {"workload_identity_token": "projected-token-1"}
+    else:
+        proof = {"credential_secret": "cred-secret"}
+    monkeypatch.setenv(SECRET_ENV, "cred-secret")
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    rejected = _Answer(
+        401,
+        {"detail": "Runtime credential exchange denied."},
+        {"WWW-Authenticate": 'Bearer realm="runtime-credential-exchange"'},
+    )
+    exchange = _Exchange(monkeypatch, rejected)
+
+    with pytest.raises(utils.AuthError, match="failed with status 401"):
+        utils.RuntimeCredentialAuthProvider().refresh(force=True)
+
+    assert exchange.bodies == [{"credential_id": "cred-id", **proof}]
+    assert exchange.sleeps == []
+
+
+def test_identity_token_stays_out_of_logs_errors_and_the_environment(
+    monkeypatch, runtime, capfd, caplog
+):
+    token = "projected-token-that-stays-in-the-exchange"
+    _use_token_file(monkeypatch, runtime, token)
+    utils = load_sdk_submodule("mainsequence.client.utils")
+    logged = []
+
+    class _Logger:
+        def __getattr__(self, level):
+            return lambda message, *args, **kwargs: logged.append(
+                f"{level} {message} {args!r} {kwargs!r}"
+            )
+
+    monkeypatch.setattr(utils, "logger", _Logger())
+    caplog.set_level(logging.DEBUG)
+    exchange = _Exchange(
+        monkeypatch,
+        _Answer(503, {"detail": "Verification is unavailable."}, {"Retry-After": "1"}),
+        _Answer(401, {"detail": "Runtime credential exchange denied."}),
+        _Answer(401, {"detail": "Runtime credential exchange denied."}),
+    )
+
+    class _Session:
+        headers = CaseInsensitiveDict()
+
+        def get(self, url, **kwargs):
+            raise AssertionError("the request must not be sent without an access token")
+
+    loaders = utils.AuthLoaders()
+    response = utils.make_request(_Session(), "GET", "https://backend.example/api/v1/x/", loaders)
+    with pytest.raises(utils.AuthError) as raised:
+        loaders.provider.refresh(force=True)
+
+    assert response.status_code == 401
+    assert [body["workload_identity_token"] for body in exchange.bodies] == [token] * 3
+    assert any("retrying in 1.0 s" in line for line in logged)
+    assert any("Auth error" in line for line in logged)
+    captured = capfd.readouterr()
+    for text in (
+        *logged,
+        caplog.text,
+        captured.out,
+        captured.err,
+        response.content.decode("utf-8"),
+        str(raised.value),
+        repr(raised.value),
+        repr(loaders.provider),
+        repr(vars(loaders.provider)),
+    ):
+        assert token not in text
+    assert all(token not in value for value in os.environ.values())
+
+
+def test_runtime_credential_is_configured_by_an_identity_token_file_or_a_secret(
+    monkeypatch, runtime
+):
+    exchange = load_sdk_submodule("mainsequence.runtime_credential_exchange")
+
+    assert exchange.runtime_credential_configured() is False
+    monkeypatch.setenv(TOKEN_FILE_ENV, str(runtime / "token"))
+    # Presence is enough: the exchange reads the file and reports a missing one.
+    assert exchange.runtime_credential_configured() is True
+    monkeypatch.delenv(TOKEN_FILE_ENV)
+    monkeypatch.setenv(SECRET_ENV, "cred-secret")
+    assert exchange.runtime_credential_configured() is True
+    monkeypatch.delenv(ID_ENV)
+    assert exchange.runtime_credential_configured() is False
+
+
+def test_logger_start_up_exchange_sends_the_identity_token_and_retries(monkeypatch, runtime):
+    _use_token_file(monkeypatch, runtime)
+    monkeypatch.setenv(SECRET_ENV, SECRET)
+    monkeypatch.setenv("JOB_RUN_UID", JOB_RUN_UID)
+    exchange = _Exchange(monkeypatch, _Answer(503, headers={"Retry-After": "1"}), _granted())
+    authorizations = []
+
+    def _get(url, **kwargs):
+        authorizations.append(kwargs["headers"].get("Authorization"))
+        return _Answer(200, {"job_run_uid": JOB_RUN_UID})
+
+    monkeypatch.setattr(requests, "get", _get)
+
+    load_sdk_submodule("mainsequence.logconf")
+
+    proof = {"credential_id": "cred-id", "workload_identity_token": "projected-token-1"}
+    assert exchange.bodies == [proof, proof]
+    assert exchange.sleeps == [1]
+    assert all(request["allow_redirects"] is False for request in exchange.requests)
+    assert authorizations == ["Bearer runtime-access"]
+
+
+def test_logger_start_up_exchange_never_falls_back_to_the_secret(monkeypatch, runtime):
+    monkeypatch.setenv(TOKEN_FILE_ENV, str(runtime / "missing-token"))
+    monkeypatch.setenv(SECRET_ENV, SECRET)
+    monkeypatch.setenv("JOB_RUN_UID", JOB_RUN_UID)
+    exchange = _Exchange(monkeypatch)
+    monkeypatch.setattr(requests, "get", lambda url, **kwargs: _Answer(401))
+
+    load_sdk_submodule("mainsequence.logconf")
+
+    assert exchange.requests == []
+    assert "MAINSEQUENCE_ACCESS_TOKEN" not in os.environ