Implement provisioned credentials

Closes #29

Author: nficano

docs/03-features/provisioned-credentials.md

@@ -0,0 +1,58 @@
+---
+title: "Provisioned credentials"
+sdk: python
+spec_sections: ["§9.7", "§9.8", "§14"]
+order: 11
+kind: feature
+---
+
+## What it is
+
+`model.use` constrains which upstream model identifiers a job may
+use. When a runtime is configured with a credential provisioner, it
+can mint short-lived credentials scoped to the job's `cost.budget`,
+`model.use`, and `lease_constraints.expires_at`, then attach them to
+`job.accepted.payload.credentials`.
+
+Credentials are issued only for the submitting session and are
+revoked when the job reaches any terminal state. List and subscribe
+surfaces intentionally omit credential values.
+
+## Feature flags
+
+- `model.use`
+- `provisioned_credentials`
+
+The runtime advertises these flags only when `credential_provisioner`
+and `revocation_log` are configured.
+
+## Python API
+
+```python
+runtime = ARCPRuntime(
+    runtime=RuntimeInfo(name="demo", version="1.1.0"),
+    bearer=StaticBearerVerifier({"demo-token": "p1"}),
+    credential_provisioner=InMemoryCredentialProvisioner(),
+    revocation_log=InMemoryRevocationLog(),
+)
+
+handle = await client.submit(
+    agent="summarize",
+    lease_request={
+        "model.use": ["tier-fast/*"],
+        "cost.budget": ["USD:5.00"],
+    },
+)
+
+credential = handle.credentials[0]
+```
+
+Inside an agent, call `ctx.authorize_model("tier-fast/mini")` before
+using a model id when the runtime is in the call path. Provisioner
+adapters can translate upstream budget failures by raising
+`UpstreamBudgetExhausted`; the runtime emits `BUDGET_EXHAUSTED`.
+
+## See also
+
+- Example: [`../04-examples/provisioned-credentials.md`](../04-examples/provisioned-credentials.md).
+- Spec: [`../../../spec/docs/draft-arcp-1.1.md`](../../../spec/docs/draft-arcp-1.1.md) §§9.7–9.8.

docs/04-examples/provisioned-credentials.md

@@ -0,0 +1,21 @@
+---
+title: "Provisioned credentials"
+sdk: python
+order: 22
+kind: example
+---
+
+A runtime installs an `InMemoryCredentialProvisioner`, advertises
+`model.use` and `provisioned_credentials`, and accepts a job whose
+lease scopes the generated credential to `tier-fast/*` and `USD:1.00`.
+
+Source: [`../../examples/provisioned_credentials/`](../../examples/provisioned_credentials/).
+
+```sh
+uv run python -m examples.provisioned_credentials.server &
+uv run python -m examples.provisioned_credentials.client
+```
+
+## See also
+
+- Feature: [`../03-features/provisioned-credentials.md`](../03-features/provisioned-credentials.md).

docs/06-conformance.md

@@ -87,6 +87,10 @@ values are `Implemented` or `Deferred` only. Citations are
 | §9.6 `cost.budget` initial snapshot      | Implemented | `arcp/_runtime/lease.py:L115`             |
 | §9.6 Per-event budget decrement          | Implemented | `arcp/_runtime/job.py:L68`                |
 | §9.6 `BUDGET_EXHAUSTED` on floor         | Implemented | `arcp/_runtime/job.py:L68`                |
+| §9.7 `model.use` authorization           | Implemented | `arcp/_runtime/job.py:L285`               |
+| §9.8 Provisioned credential interface    | Implemented | `arcp/_runtime/credentials.py:L1`         |
+| §9.8 Issue credentials on job acceptance | Implemented | `arcp/_runtime/_handlers.py:L158`         |
+| §9.8 Revoke credentials on terminal state | Implemented | `arcp/_runtime/_job_runner.py:L145`      |
 
 ## §10 Delegation
 

examples/provisioned_credentials/README.md

@@ -0,0 +1,14 @@
+# Provisioned Credentials
+
+This example runs a vendor-neutral credential provisioner. The runtime
+issues one deterministic bearer credential when the job is accepted and
+revokes it when the job completes.
+
+```sh
+uv run python -m examples.provisioned_credentials.server
+uv run python -m examples.provisioned_credentials.client
+```
+
+The in-memory provisioner is a test double. Production adapters should
+implement `CredentialProvisioner` against a gateway such as LiteLLM
+without adding that vendor dependency to the SDK core.

examples/provisioned_credentials/client.py

@@ -0,0 +1,46 @@
+"""provisioned_credentials client — reads credentials from job.accepted."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import sys
+
+from arcp import ClientInfo, WebSocketTransport
+from arcp.client import ARCPClient
+
+PORT = int(os.environ.get("ARCP_DEMO_PORT", "7892"))
+URL = os.environ.get("ARCP_DEMO_URL", f"ws://127.0.0.1:{PORT}/arcp")
+TOKEN = os.environ.get("ARCP_DEMO_TOKEN", "demo-token")
+
+
+async def main() -> int:
+    client = ARCPClient(
+        client=ClientInfo(name="provisioned-credentials-client", version="1.1.0"),
+        token=TOKEN,
+        features=("model.use", "provisioned_credentials", "cost.budget"),
+    )
+    async with contextlib.aclosing(client):
+        transport = await WebSocketTransport.connect(URL)
+        await client.connect(transport)
+        handle = await client.submit(
+            agent="model-user",
+            input={"model": "tier-fast/demo"},
+            lease_request={
+                "model.use": ["tier-fast/*"],
+                "cost.budget": ["USD:1.00"],
+            },
+        )
+        credential = handle.credentials[0]
+        print(
+            f"credential id={credential.id} scheme={credential.scheme} endpoint={credential.endpoint}"
+        )
+        result = await handle.done
+        assert result.final_status == "success"
+        assert result.result == {"model": "tier-fast/demo", "credential_count": 1}
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

examples/provisioned_credentials/server.py

@@ -0,0 +1,49 @@
+"""provisioned_credentials server — issues a lease-bound bearer credential (§9.8)."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from arcp import RuntimeInfo, serve_websocket
+from arcp.runtime import (
+    ARCPRuntime,
+    InMemoryCredentialProvisioner,
+    InMemoryRevocationLog,
+    JobContext,
+    StaticBearerVerifier,
+)
+
+PORT = int(os.environ.get("ARCP_DEMO_PORT", "7892"))
+TOKEN = os.environ.get("ARCP_DEMO_TOKEN", "demo-token")
+
+
+async def model_user(input_value: dict, ctx: JobContext) -> dict:
+    model = str(input_value.get("model", "tier-fast/demo"))
+    ctx.authorize_model(model)
+    await ctx.status("using_model", model)
+    return {"model": model, "credential_count": len(ctx.credentials)}
+
+
+async def main() -> None:
+    provisioner = InMemoryCredentialProvisioner()
+    runtime = ARCPRuntime(
+        runtime=RuntimeInfo(name="provisioned-credentials-server", version="1.1.0"),
+        bearer=StaticBearerVerifier({TOKEN: "demo-principal"}),
+        credential_provisioner=provisioner,
+        revocation_log=InMemoryRevocationLog(),
+    )
+    runtime.register_agent("model-user", model_user)
+    server = await serve_websocket(runtime.accept, host="127.0.0.1", port=PORT, path="/arcp")
+    print(f"listening on ws://127.0.0.1:{PORT}/arcp")
+    try:
+        await asyncio.Future()
+    finally:
+        print(f"revoked={provisioner.revoked}")
+        server.close()
+        await server.wait_closed()
+        await runtime.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/arcp/__init__.py

@@ -25,6 +25,8 @@
     error_from_payload,
 )
 from ._messages.execution import (
+    CredentialConstraintsPayload,
+    CredentialPayload,
     Lease,
     LeaseConstraints,
     parse_agent_ref,
@@ -38,6 +40,7 @@
     SessionResume,
     SessionWelcomePayload,
 )
+from ._runtime.credentials import Credential, CredentialConstraints
 from ._transport.base import Transport, TransportClosed
 from ._transport.in_memory import MemoryTransport, pair_memory_transports
 from ._transport.stdio import StdioTransport
@@ -59,6 +62,10 @@
     # messages (commonly-used)
     "Capabilities",
     "ClientInfo",
+    "Credential",
+    "CredentialConstraints",
+    "CredentialConstraintsPayload",
+    "CredentialPayload",
     "DuplicateKeyError",
     # envelope
     "Envelope",

src/arcp/_client/handles.py

@@ -9,6 +9,7 @@
 from typing import Any
 
 from .._messages.execution import (
+    CredentialPayload,
     JobAcceptedPayload,
     JobResultPayload,
     Lease,
@@ -43,6 +44,10 @@ def lease_constraints(self) -> LeaseConstraints | None:
     def budget(self) -> dict[str, str] | None:
         return self.accepted.budget
 
+    @property
+    def credentials(self) -> tuple[CredentialPayload, ...]:
+        return self.accepted.credentials or ()
+
     @property
     def trace_id(self) -> str | None:
         return self.accepted.trace_id

src/arcp/_logger.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from copy import deepcopy
 from typing import Any
 
 import structlog
@@ -39,4 +40,26 @@ def get_logger(name: str | None = None, **initial: Any) -> Any:
     return log
 
 
-__all__ = ("get_logger",)
+def redact_credentials(obj: Any) -> Any:
+    """Return a copy with every `credentials[*].value` replaced by `<redacted>`."""
+    out = deepcopy(obj)
+    _redact_credentials_in_place(out)
+    return out
+
+
+def _redact_credentials_in_place(obj: Any) -> None:
+    if isinstance(obj, dict):
+        mapping: dict[Any, Any] = obj
+        credentials = mapping.get("credentials")
+        if isinstance(credentials, (list, tuple)):
+            for cred in credentials:
+                if isinstance(cred, dict) and "value" in cred:
+                    cred["value"] = "<redacted>"
+        for value in mapping.values():
+            _redact_credentials_in_place(value)
+    elif isinstance(obj, (list, tuple)):
+        for item in obj:
+            _redact_credentials_in_place(item)
+
+
+__all__ = ("get_logger", "redact_credentials")

src/arcp/_messages/execution.py

@@ -110,6 +110,23 @@ def _check_agent(cls, v: str) -> str:
         parse_agent_ref(v)
         return v
 
+class CredentialConstraintsPayload(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    cost_budget: tuple[str, ...] = Field(default=(), alias="cost.budget")
+    model_use: tuple[str, ...] = Field(default=(), alias="model.use")
+    expires_at: str | None = None
+
+
+class CredentialPayload(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    id: str
+    scheme: Literal["bearer"]
+    value: str
+    endpoint: str
+    profile: str | None = None
+    constraints: CredentialConstraintsPayload | None = None
+
+
 class JobAcceptedPayload(BaseModel):
     model_config = ConfigDict(extra="allow")
     job_id: str
@@ -121,6 +138,7 @@ class JobAcceptedPayload(BaseModel):
     parent_job_id: str | None = None
     delegate_id: str | None = None
     trace_id: str | None = None
+    credentials: tuple[CredentialPayload, ...] | None = None
 
 class JobCancelPayload(BaseModel):
     model_config = ConfigDict(extra="allow")
@@ -183,6 +201,8 @@ class JobUnsubscribePayload(BaseModel):
 __all__ = (
     "EVENT_KINDS",
     "ArtifactRefBody",
+    "CredentialConstraintsPayload",
+    "CredentialPayload",
     "DelegateBody",
     "JobAcceptedPayload",
     "JobCancelPayload",