chore: sync deixic-python from Mono

.repository-projection.json

@@ -3,11 +3,11 @@
   "projection": "deixic-python",
   "projectionSchemaVersion": 1,
   "sourceRepository": "dx-corp/mono",
-  "sourceSha": "ddaee8a19ef06ccd953aa67505182ec41e78f13c",
+  "sourceSha": "80416a066acccdb2394733a9db4adcae19d88f23",
   "destinationRepository": "dx-corp/deixic-python",
-  "priorProjectedBase": "334735fa42a46ba1f3bd05f768a31d3bcbcda394",
-  "definitionDigest": "01efa736c67353b6c6e353d7e2ab6886ecd21b68f31fe1a89234403247abcbdb",
-  "toolDigest": "0aae6000dbd0940f5a0af380463ccb5a83285eda",
-  "contentDigest": "14e4cd30768fa913750e0b17c4bca966269f33b72c226ac8924df966c045fbcf",
+  "priorProjectedBase": "be2ecd40236afbb15ee257b69e86ec6832226803",
+  "definitionDigest": "eedaf99642ef977b56b6e12ce151e1834670560f00294e89224f0628882937d9",
+  "toolDigest": "cef8579e533dbfa40cbd9070dd7581f65f800e5f",
+  "contentDigest": "13e942ba6333d3a42f22f7aeb9a324042fc4e8a56c52eaa28c67814b696f8a3b",
   "publicationEligible": true
 }

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `WorkloadFederationCredentialProvider` with GitHub Actions, file, and
+  environment-variable assertion sources for keyless workload authentication.
 - Report missing or removed model routes during setup instead of declaring the
   workspace accessible, and preserve plain-text account briefs when account
   names contain structured-output instruction text. Keep rejected credential

README.md

@@ -219,6 +219,77 @@ provide a `CredentialProvider`; an authentication replay is allowed only when
 the refreshed credential retains the same subject, tenant, and declared
 scopes.
 
+## Workload federation
+
+A CI job or cloud workload can authenticate without a stored API key. An
+organization admin first registers an issuer, a service account, and a rule in
+Identity settings, as described in the
+[workload federation guide](https://github.com/dx-corp/mono/blob/main/docs/services/identity/workload-federation.md).
+The workload then exchanges a signed assertion from its platform for a Deixic
+access token that lasts at most 300 seconds:
+
+```python
+import os
+
+from deixic import (
+    Deixic,
+    WorkloadFederationCredentialProvider,
+    github_actions_assertion_source,
+)
+
+identity_url = os.environ["DEIXIC_IDENTITY_URL"]
+credentials = WorkloadFederationCredentialProvider(
+    identity_url=identity_url,
+    assertion_source=github_actions_assertion_source(
+        audience=f"{identity_url}/v1/workload-federation/exchange",
+    ),
+)
+deixic = Deixic(
+    credential_provider=credentials,
+    organization_id="org_123",
+    workspace_id="ws_456",
+)
+```
+
+The provider exchanges an assertion on the first request and caches the token.
+It exchanges again 60 seconds before expiry (`refresh_margin`) and after an
+HTTP 401 from Deixic. Identity accepts each assertion once, so every exchange
+calls the assertion source for a new assertion. The provider refuses to send
+an assertion it has already exchanged and raises `DeixicError` with code
+`workload_assertion_reused`. When an early refresh cannot obtain a new
+assertion and the cached token has not expired, the provider keeps using the
+cached token.
+
+Assertion sources:
+
+- `github_actions_assertion_source(audience)` requests a new OIDC token from
+  GitHub Actions on each call. The job needs `permissions: id-token: write`.
+- `file_assertion_source(path)` reads a file on each call, such as a Kubernetes
+  projected service-account token. The kubelet rewrites that file after 80% of
+  the token's `expirationSeconds`. A file token can therefore be exchanged once
+  per rotation. Set `expirationSeconds` so that rotation happens more often
+  than the 300-second Deixic token lifetime, or pass a callable that requests
+  a new token from the Kubernetes TokenRequest API.
+- `environment_assertion_source(name)` reads an environment variable on each
+  call. The application must write a new value before each exchange.
+- Any zero-argument callable that returns a new JWT string.
+
+Exchange failures raise `DeixicError`:
+
+| HTTP status | `kind` | `code` | Retried |
+| --- | --- | --- | --- |
+| 400 | `validation` | `workload_assertion_invalid` | No |
+| 403 | `authorization` | `workload_federation_forbidden` | No |
+| 409 | `conflict` | `workload_assertion_replayed` | No |
+| 503 | `unavailable` | `workload_federation_unavailable` | Yes |
+| Transport failure | `transport` | `workload_exchange_transport` | Yes |
+
+A retry waits `retry_delay` seconds, doubled on each attempt, up to
+`max_attempts` total attempts (default 3). Each retry uses a new assertion.
+A 403 means no active rule matched the assertion's issuer, audience, subject,
+and claims. The provider never logs the assertion or the access token and
+omits both from error messages.
+
 ## Coding output readback
 
 `messages.send(coding_acceptance=contract)` sends the typed coding contract and

src/deixic/__init__.py

@@ -1,9 +1,17 @@
 from .auth import Credential, CredentialProvider
 from .client import Deixic
 from .errors import DeixicError
+from .federation import (
+    AssertionSource,
+    WorkloadFederationCredentialProvider,
+    environment_assertion_source,
+    file_assertion_source,
+    github_actions_assertion_source,
+)
 from .tasks import SetupCheck, Task, TaskCheckpoint, TaskResult
 
 __all__ = [
+    "AssertionSource",
     "Credential",
     "CredentialProvider",
     "Deixic",
@@ -12,4 +20,8 @@
     "Task",
     "TaskCheckpoint",
     "TaskResult",
+    "WorkloadFederationCredentialProvider",
+    "environment_assertion_source",
+    "file_assertion_source",
+    "github_actions_assertion_source",
 ]