ms-tau-sdk 1.3.0.dev27__tar.gz → 1.4.0.dev28__tar.gz

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.4.0 — 2026-10-05
+
+- A managed runtime can prove its runtime credential with a projected workload identity token
+  instead of the bootstrap secret. With the new `MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE` setting,
+  the runtime credential exchange reads that file for every exchange, because the token in it is
+  rotated, and sends `credential_id` with `workload_identity_token`. In this mode the SDK never
+  reads or sends `MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET`, and the configuration check no longer
+  requires it. A missing, unreadable, or empty token file is a configuration error that names the
+  file, and the exchange never falls back to the secret. The token stays inside the exchange: it is
+  not kept in the settings, the environment, or a file, and never appears in a log or an error
+  message. Without the setting, the exchange sends the secret as before. In both modes, an
+  exchange answered with HTTP 429 or 503 is sent again up to three times, after waiting as long as
+  `Retry-After` asks (at most 60 seconds) or 1, 2, then 4 seconds without it; a longer
+  `Retry-After` fails at once. HTTP 401 fails at once, without a retry or another proof. The
+  `runtime.auth.exchange.completed` log event names the proof in `proof` and now also reports
+  failed exchanges. See the 2026-10-05 amendment of ADR 0002
+  ([#56](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/56)).
+- Printing or logging the settings no longer shows the runtime credential secret. `repr()` and
+  `str()` of `TauSDKSettings` showed `MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET` in plain text, and so
+  did every log event that carried the settings object. Three other objects showed a credential
+  the same way, and now leave it out of `repr()` and `str()`:
+  - `AccessToken`: the Main Sequence access token;
+  - `ProviderCredential`: the key that an `organization_custom` credential carries in `headers`;
+  - `TauRuntimeBootstrap`: the hydrated provider credentials in `provider_credentials`.
+
+  A settings validation error no longer repeats the configured values. When the secret or a
+  local token was the last value configured, the error printed its last characters. The error
+  still names the variable and the problem. The SDK reads and sends every value as before, and
+  `runtime_credential_secret` is still a `str`
+  ([#57](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/57)).
+
 ## 1.3.0 — 2026-10-05
 
 - Project skills stay available with `TAU_EXCLUDE_BASE_TOOLS=true`. Tau lists skills in the system

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 1.3.0.dev27
+Version: 1.4.0.dev28
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs
@@ -90,6 +90,11 @@ export MAINSEQUENCE_RUNTIME_CREDENTIAL_ID="<runtime-credential-id>"
 export MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET="<runtime-credential-secret>"
 ```
 
+A runtime that Main Sequence deploys with a projected workload identity token gets
+`MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE` instead of the secret. The SDK then reads the token from
+that file for every exchange and never uses a secret. See
+[Settings and credentials](docs/reference/settings.md#managed-authenticated-startup).
+
 Start the service from the project workspace:
 
 ```bash

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/README.md

@@ -59,6 +59,11 @@ export MAINSEQUENCE_RUNTIME_CREDENTIAL_ID="<runtime-credential-id>"
 export MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET="<runtime-credential-secret>"
 ```
 
+A runtime that Main Sequence deploys with a projected workload identity token gets
+`MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE` instead of the secret. The SDK then reads the token from
+that file for every exchange and never uses a secret. See
+[Settings and credentials](docs/reference/settings.md#managed-authenticated-startup).
+
 Start the service from the project workspace:
 
 ```bash

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "1.3.0.dev27"
+version = "1.4.0.dev28"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/src/ms_tau_sdk/backend/auth.py

@@ -9,9 +9,11 @@ import math
 import os
 import subprocess
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 from pathlib import Path
-from typing import Protocol
+from typing import Literal, Protocol
 from urllib.parse import urlsplit
 
 import httpx
@@ -22,6 +24,8 @@ from ms_tau_sdk.settings import (
     ACCESS_TOKEN_ENV,
     ENV_FILE,
     REFRESH_TOKEN_ENV,
+    RUNTIME_CREDENTIAL_SECRET_ENV,
+    RUNTIME_IDENTITY_TOKEN_FILE_ENV,
     TauSDKSettings,
 )
 
@@ -32,6 +36,16 @@ JWT_REFRESH_PATH = "/auth/jwt-token/token/refresh/"
 CLI_TOKEN_COMMAND = ("auth", "token", "--json")
 CLI_TOKEN_TIMEOUT_SECONDS = 15.0
 CLI_TOKEN_REUSE_MARGIN_SECONDS = 60
+# The runtime credential exchange retries the answers that mean "not now": 429 (throttled) and
+# 503 (verification temporarily unavailable). A 401 is final.
+EXCHANGE_RETRY_STATUS_CODES = frozenset({429, 503})
+EXCHANGE_MAX_RETRIES = 3
+EXCHANGE_RETRY_BASE_DELAY_SECONDS = 1.0
+EXCHANGE_MAX_RETRY_DELAY_SECONDS = 60.0
+# A projected token is a JWT of a few kilobytes. A larger file is not a token file.
+IDENTITY_TOKEN_MAX_BYTES = 64 * 1024
+
+type RuntimeCredentialProof = Literal["workload_identity_token", "credential_secret"]
 
 
 class BackendAuth(Protocol):
@@ -46,7 +60,7 @@ class BackendAuth(Protocol):
 
 @dataclass(slots=True)
 class AccessToken:
-    value: str
+    value: str = field(repr=False)  # the bearer token itself never appears in repr() or str()
     token_type: str
     expires_at: float | None
 
@@ -54,7 +68,94 @@ class AccessToken:
         return self.expires_at is not None and self.expires_at <= time.time() + skew_seconds
 
 
+def _read_workload_identity_token(path: Path) -> str:
+    """Read the projected workload identity token for one exchange.
+
+    The token file is rotated, so it is read for every exchange and the token is never cached.
+    The token leaves this function only as its return value. An error names the file and the
+    reason, never any of its content, and no error falls back to the runtime credential secret.
+    """
+
+    def unusable(reason: str) -> ConfigurationError:
+        return ConfigurationError(
+            f"{RUNTIME_IDENTITY_TOKEN_FILE_ENV} names {path}, which {reason}. The runtime "
+            f"credential exchange does not fall back to {RUNTIME_CREDENTIAL_SECRET_ENV}."
+        )
+
+    try:
+        with path.open("rb") as handle:
+            content = handle.read(IDENTITY_TOKEN_MAX_BYTES + 1)
+    except OSError as error:
+        raise unusable(f"cannot be read ({error.strerror or type(error).__name__})") from None
+    if len(content) > IDENTITY_TOKEN_MAX_BYTES:
+        raise unusable(
+            f"is larger than {IDENTITY_TOKEN_MAX_BYTES // 1024} KiB, too large for a token"
+        )
+    try:
+        token: str | None = content.decode("utf-8").strip()
+    except UnicodeDecodeError:
+        # Raised outside this handler, so the decoding error and the bytes it holds stay behind.
+        token = None
+    if token is None:
+        raise unusable("does not hold text")
+    if not token:
+        raise unusable("is empty")
+    return token
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Return the wait a ``Retry-After`` header asks for, or None when there is no usable one."""
+
+    value = response.headers.get("Retry-After", "").strip()
+    if not value:
+        return None
+    if value.isascii() and value.isdigit():
+        return float(value)
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, (when - datetime.now(UTC)).total_seconds())
+
+
+def _exchange_retry_delay(response: httpx.Response, *, retry: int) -> float:
+    """Wait as long as the platform asks, or back off exponentially when it does not say."""
+
+    asked = _retry_after_seconds(response)
+    if asked is not None:
+        return asked
+    return EXCHANGE_RETRY_BASE_DELAY_SECONDS * 2.0 ** (retry - 1)
+
+
+def _rejection_message(proof: RuntimeCredentialProof) -> str:
+    """Explain a 401 from the exchange by the names of the settings involved, never a value."""
+
+    if proof == "workload_identity_token":
+        return (
+            "Runtime credential exchange was rejected (HTTP 401): the platform did not accept "
+            f"the workload identity token read from {RUNTIME_IDENTITY_TOKEN_FILE_ENV}. A rejected "
+            "token is not retried, and the exchange does not fall back to "
+            f"{RUNTIME_CREDENTIAL_SECRET_ENV}."
+        )
+    return (
+        "Runtime credential exchange was rejected (HTTP 401): the platform did not accept "
+        f"{RUNTIME_CREDENTIAL_SECRET_ENV}. A rejected credential is not retried."
+    )
+
+
 class RuntimeCredentialAuth:
+    """Exchange the managed runtime credential for short-lived Main Sequence access tokens.
+
+    The exchange proves the credential in one of two ways. With
+    ``MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE`` set, it sends the projected workload identity
+    token read from that file for every exchange, and never the secret. Without it, it sends
+    ``MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET``. The token stays inside the exchange: it is not
+    kept on this object, in the settings, or in the environment, and it is never logged or put
+    in an error.
+    """
+
     def __init__(
         self,
         settings: TauSDKSettings,
@@ -79,6 +180,12 @@ class RuntimeCredentialAuth:
         """Authenticate during process startup so readiness is truthful."""
         await self._access_token(force=False)
 
+    def _proof(self) -> RuntimeCredentialProof:
+        """Name the proof the exchange sends. It is a field name, never a value."""
+        if self.settings.runtime_identity_token_file is not None:
+            return "workload_identity_token"
+        return "credential_secret"
+
     async def _access_token(self, *, force: bool) -> AccessToken:
         if not force and self._token is not None and not self._token.needs_refresh():
             return self._token
@@ -86,30 +193,25 @@ class RuntimeCredentialAuth:
             if not force and self._token is not None and not self._token.needs_refresh():
                 return self._token
             self.settings.validate_runtime_auth()
-            if (
-                not self.settings.runtime_credential_id
-                or not self.settings.runtime_credential_secret
-            ):
-                raise ConfigurationError("Runtime credentials are not configured")
+            proof = self._proof()
             client = self._client or httpx.AsyncClient(timeout=10)
             close_client = self._client is None
             started_at = time.monotonic()
             try:
-                response = await client.post(
-                    f"{self.settings.backend_url.rstrip('/')}{RUNTIME_CREDENTIAL_TOKEN}",
-                    json={
-                        "credential_id": self.settings.runtime_credential_id,
-                        "credential_secret": self.settings.runtime_credential_secret,
-                    },
+                response, attempts = await self._exchange(client, proof)
+            except Exception as failure:
+                logger.warning(
+                    "runtime.auth.exchange.completed",
+                    duration_ms=round((time.monotonic() - started_at) * 1000, 3),
+                    outcome="failed",
+                    proof=proof,
+                    error_type=type(failure).__name__,
+                    status_code=getattr(failure, "backend_status", None),
                 )
+                raise
             finally:
                 if close_client:
                     await client.aclose()
-            if not response.is_success:
-                raise BackendError(
-                    "Runtime credential exchange failed",
-                    status_code=response.status_code,
-                )
             data = response.json()
             value = str(data.get("access") or "").strip()
             if not value:
@@ -129,9 +231,75 @@ class RuntimeCredentialAuth:
                 "runtime.auth.exchange.completed",
                 duration_ms=round((time.monotonic() - started_at) * 1000, 3),
                 outcome="success",
+                proof=proof,
+                attempts=attempts,
             )
             return self._token
 
+    async def _exchange(
+        self,
+        client: httpx.AsyncClient,
+        proof: RuntimeCredentialProof,
+    ) -> tuple[httpx.Response, int]:
+        """Send the exchange, and send it again a bounded number of times after 429 or 503."""
+        url = f"{self.settings.backend_url.rstrip('/')}{RUNTIME_CREDENTIAL_TOKEN}"
+        attempt = 1
+        while True:
+            # Each attempt builds its request again, so a rotated token file is read again.
+            response = await client.post(url, json=await self._exchange_body())
+            status = response.status_code
+            if response.is_success:
+                return response, attempt
+            if status == 401:
+                raise BackendError(_rejection_message(proof), status_code=status)
+            if status not in EXCHANGE_RETRY_STATUS_CODES:
+                raise BackendError(
+                    f"Runtime credential exchange failed (HTTP {status})", status_code=status
+                )
+            meaning = (
+                "the platform throttled the exchange"
+                if status == 429
+                else "the platform could not verify the runtime credential"
+            )
+            if attempt > EXCHANGE_MAX_RETRIES:
+                raise BackendError(
+                    f"Runtime credential exchange failed (HTTP {status}) after {attempt} "
+                    f"attempts: {meaning}. Try again later.",
+                    status_code=status,
+                )
+            delay = _exchange_retry_delay(response, retry=attempt)
+            if delay > EXCHANGE_MAX_RETRY_DELAY_SECONDS:
+                raise BackendError(
+                    f"Runtime credential exchange failed (HTTP {status}): {meaning} and asked "
+                    f"to retry after {delay:.0f} seconds, longer than the "
+                    f"{EXCHANGE_MAX_RETRY_DELAY_SECONDS:.0f} seconds the SDK waits.",
+                    status_code=status,
+                )
+            logger.warning(
+                "runtime.auth.exchange.retrying",
+                status_code=status,
+                attempt=attempt,
+                max_attempts=EXCHANGE_MAX_RETRIES + 1,
+                delay_seconds=delay,
+                proof=proof,
+            )
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def _exchange_body(self) -> dict[str, str]:
+        """Build one exchange request. It carries exactly one proof of the credential."""
+        credential_id = self.settings.runtime_credential_id
+        if not credential_id:
+            raise ConfigurationError("Runtime credentials are not configured")
+        token_file = self.settings.runtime_identity_token_file
+        if token_file is not None:
+            token = await asyncio.to_thread(_read_workload_identity_token, token_file)
+            return {"credential_id": credential_id, "workload_identity_token": token}
+        secret = self.settings.runtime_credential_secret
+        if not secret:
+            raise ConfigurationError("Runtime credentials are not configured")
+        return {"credential_id": credential_id, "credential_secret": secret}
+
 
 def _jwt_expiry(token: str) -> int | None:
     """Read an unverified expiry only to decide when authenticated refresh is due."""

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/src/ms_tau_sdk/backend/models.py

@@ -355,7 +355,9 @@ class TauRuntimeBootstrap(BackendModel):
     runtime_state: RuntimeState
     history: SessionEntryList
     resume_snapshot: TauResumeSnapshot | None = None
-    provider_credentials: dict[str, Any]
+    # The hydrated provider credentials hold their keys in plain text, so they never appear in
+    # repr() or str().
+    provider_credentials: dict[str, Any] = Field(repr=False)
     provider_control: ProviderControl
     runtime_capabilities: dict[str, str]
     bootstrap_replayed: bool = False
@@ -394,7 +396,9 @@ class ProviderCredential(BackendModel):
     expires_at: datetime | None = None
     account_id: str | None = None
     base_url: str | None = None
-    headers: dict[str, str] = Field(default_factory=dict)
+    # An organization_custom credential carries its key in a header, so the headers never appear
+    # in repr() or str().
+    headers: dict[str, str] = Field(default_factory=dict, repr=False)
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     def secret(self) -> str:

{ms_tau_sdk-1.3.0.dev27 → ms_tau_sdk-1.4.0.dev28}/src/ms_tau_sdk/settings.py

@@ -18,6 +18,9 @@ from .errors import ConfigurationError
 ENV_FILE = ".env"
 ACCESS_TOKEN_ENV = "MAINSEQUENCE_ACCESS_TOKEN"
 REFRESH_TOKEN_ENV = "MAINSEQUENCE_REFRESH_TOKEN"
+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"
 MAINSEQUENCE_CLI_ENV = "MAINSEQUENCE_CLI"
 MAINSEQUENCE_CLI_NAME = "mainsequence"
 LocalAuthSource = Literal["environment", "env_file", "cli"]
@@ -60,6 +63,9 @@ class TauSDKSettings(BaseSettings):
         case_sensitive=True,
         extra="ignore",
         populate_by_name=True,
+        # The input holds credentials, so a validation error names the setting and the problem
+        # but never echoes the configured values.
+        hide_input_in_errors=True,
     )
 
     backend_url: str = Field(
@@ -72,11 +78,21 @@ class TauSDKSettings(BaseSettings):
     )
     runtime_credential_id: str | None = Field(
         default=None,
-        validation_alias="MAINSEQUENCE_RUNTIME_CREDENTIAL_ID",
+        validation_alias=RUNTIME_CREDENTIAL_ID_ENV,
     )
+    # A plain string, read by the exchange that sends it. It never appears in repr() or str(), so
+    # printing or logging the settings does not show it.
     runtime_credential_secret: str | None = Field(
         default=None,
-        validation_alias="MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET",
+        validation_alias=RUNTIME_CREDENTIAL_SECRET_ENV,
+        repr=False,
+    )
+    # The file that holds the runtime's projected workload identity token. When it is set, the
+    # runtime credential exchange proves the credential with that token instead of the secret.
+    # Only the path is a setting: the token is read by each exchange and never kept here.
+    runtime_identity_token_file: Path | None = Field(
+        default=None,
+        validation_alias=RUNTIME_IDENTITY_TOKEN_FILE_ENV,
     )
     access_token: SecretStr | None = Field(
         default=None,
@@ -325,9 +341,9 @@ class TauSDKSettings(BaseSettings):
         normalized = str(value or "").strip()
         return normalized or None
 
-    @field_validator("mainsequence_cli", mode="before")
+    @field_validator("mainsequence_cli", "runtime_identity_token_file", mode="before")
     @classmethod
-    def ignore_blank_mainsequence_cli(cls, value: object) -> object:
+    def ignore_blank_paths(cls, value: object) -> object:
         if isinstance(value, str) and not value.strip():
             return None
         return value
@@ -438,9 +454,12 @@ class TauSDKSettings(BaseSettings):
             return
         missing = []
         if not self.runtime_credential_id:
-            missing.append("MAINSEQUENCE_RUNTIME_CREDENTIAL_ID")
-        if not self.runtime_credential_secret:
-            missing.append("MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET")
+            missing.append(RUNTIME_CREDENTIAL_ID_ENV)
+        # The credential is proven with the projected workload identity token or with the
+        # secret. With a token file the secret is not needed. The file itself is read, and a
+        # missing or empty file reported, by each exchange, because the token is rotated.
+        if self.runtime_identity_token_file is None and not self.runtime_credential_secret:
+            missing.append(f"{RUNTIME_CREDENTIAL_SECRET_ENV} or {RUNTIME_IDENTITY_TOKEN_FILE_ENV}")
         if missing:
             raise ConfigurationError("Missing runtime credential settings: " + ", ".join(missing))