feat: close #55 provisioned credentials

Author: Nick Ficano

CONFORMANCE.md

@@ -81,7 +81,7 @@ new v1.1 subsections appear after them.
 | Requirement                                                                                               | Status      | Location                                                                                                  |
 | --------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
 | §9.1 Lease is IMMUTABLE, granted at submit; capability → glob pattern[]                                   | Implemented | `packages/core/src/messages/execution.ts:LeaseSchema`; `packages/runtime/src/lease.ts:validateLeaseShape` |
-| §9.2 Reserved namespaces `fs.read`, `fs.write`, `net.fetch`, `tool.call`, `agent.delegate`, `cost.budget` | Implemented | `packages/core/src/messages/execution.ts:RESERVED_CAPABILITY_NAMES`                                       |
+| §9.2 Reserved namespaces `fs.read`, `fs.write`, `net.fetch`, `tool.call`, `agent.delegate`, `cost.budget`, `model.use` | Implemented | `packages/core/src/messages/lease-schema.ts:RESERVED_CAPABILITY_NAMES`                                    |
 | §9.2 Glob `*` (single segment) / `**` (zero+ segments); anchored                                          | Implemented | `packages/runtime/src/lease.ts:compileGlob`/`matchGlob`                                                   |
 | §9.3 Runtime MUST validate every operation against the lease; `PERMISSION_DENIED` on fail                 | Implemented | `packages/runtime/src/lease.ts:validateLeaseOp`                                                           |
 | §9.4 Lease subsetting for delegation                                                                      | Implemented | `packages/runtime/src/lease.ts:isLeaseSubset`/`assertLeaseSubset`                                         |
@@ -201,6 +201,8 @@ capability list in `session.hello`/`session.welcome`.
 | `subscribe`        | §7.6     | Implemented | `packages/runtime/src/server.ts:handleJobSubscribe`; `ARCPClient.subscribe`                                                                              |
 | `lease_expires_at` | §9.5     | Implemented | `packages/runtime/src/lease.ts:validateLeaseConstraints`; expiry watchdog in `server.ts:runHandler`                                                      |
 | `cost.budget`      | §9.6     | Implemented | `packages/runtime/src/lease.ts:initialBudgetFromLease`; `Job.applyCostMetric`; `validateLeaseOp` budget check                                            |
+| `model.use`        | §9.7     | Implemented | `packages/core/src/messages/lease-schema.ts:RESERVED_CAPABILITY_NAMES`; `packages/runtime/src/lease.ts:validateLeaseOp`                                  |
+| `provisioned_credentials` | §9.8 | Implemented | `packages/runtime/src/credential-provisioner.ts`; `packages/runtime/src/job-runner.ts:issueCredentials`                                                   |
 | `progress`         | §8.2     | Implemented | `packages/core/src/messages/execution.ts:ProgressBodySchema`; `JobContext.progress`                                                                      |
 | `result_chunk`     | §8.4     | Implemented | `packages/core/src/messages/execution.ts:ResultChunkBodySchema`; `JobContext.streamResult` + `JobHandle.collectChunks`                                   |
 | `agent_versions`   | §7.5     | Implemented | `packages/core/src/messages/execution.ts:parseAgentRef`; `ARCPServer.registerAgentVersion`/`setDefaultAgentVersion`/`resolveAgent`                       |
@@ -345,6 +347,22 @@ Helpers:
 | Runtime MAY emit `cost.budget.remaining` metric events with debounce                                                | Implemented | `packages/runtime/src/server.ts:metricInterceptor` + `Job.shouldEmitBudgetRemaining` (5 % threshold)                   |
 | `JobContext.budget` read-only snapshot of remaining counters                                                        | Implemented | `packages/runtime/src/job.ts:makeJobContext`                                                                           |
 
+## §9.7 / §9.8 Model Use and Provisioned Credentials
+
+| Requirement                                                                    | Status      | Location                                                                                                        |
+| ------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
+| Feature flags `model.use` and `provisioned_credentials`                        | Implemented | `packages/core/src/version.ts:V1_1_FEATURES`                                                                    |
+| `model.use` in `RESERVED_CAPABILITY_NAMES`                                      | Implemented | `packages/core/src/messages/lease-schema.ts:RESERVED_CAPABILITY_NAMES`                                          |
+| `model.use` glob matching and lease subsetting                                  | Implemented | `packages/runtime/src/lease.ts:validateLeaseOp`; `packages/runtime/src/lease.ts:isLeaseSubset`                  |
+| Credential wire shape `{ id, scheme, value, endpoint, profile?, constraints? }` | Implemented | `packages/core/src/messages/credentials.ts`; `packages/core/src/messages/execution.ts:JobAcceptedPayloadSchema` |
+| Runtime issues credentials before `job.accepted` when a provisioner is set      | Implemented | `packages/runtime/src/job-runner.ts:issueCredentials`                                                           |
+| Runtime revokes stored credential ids on terminal cleanup                       | Implemented | `packages/runtime/src/job.ts:revokeAll`; `packages/runtime/src/credential-store.ts`                             |
+| Runtime only advertises credential features when a provisioner is configured    | Implemented | `packages/runtime/src/server.ts:advertisedFeatures`                                                             |
+| `credentialProvisioner` requires `credentialStore`                              | Implemented | `packages/runtime/src/server.ts:ARCPServer` constructor                                                         |
+| `job.subscribed` redacts credentials for non-submitters                         | Implemented | `packages/runtime/src/server-subscribe.ts:buildSubscribedPayload`                                               |
+| Client surfaces accepted credentials on `JobHandle.credentials`                 | Implemented | `packages/client/src/client-handle.ts`; `packages/client/src/client-dispatch.ts`                                |
+| Upstream spend-cap failures can be translated to `BUDGET_EXHAUSTED`             | Implemented | `packages/runtime/src/credential-provisioner.ts:toBudgetExhausted`                                              |
+
 ## §11 Trace attributes (v1.1 additions)
 
 | Requirement                                                                             | Status      | Location                                                  |

docs/guides/credentials.md

@@ -0,0 +1,88 @@
+# Provisioned Credentials (§9.8)
+
+Provisioned credentials let a runtime mint short-lived, scope-restricted
+secrets for a job after the effective lease is finalized. The client
+receives the credential in `job.accepted.payload.credentials`; the
+runtime revokes it when the job reaches a terminal state.
+
+## Runtime Setup
+
+Configure both a `CredentialProvisioner` and a `CredentialStore`:
+
+```ts
+import {
+  ARCPServer,
+  InMemoryCredentialStore,
+  type CredentialProvisioner,
+} from "@arcp/sdk";
+
+const provisioner: CredentialProvisioner = {
+  async issue(ctx) {
+    const models = ctx.lease["model.use"] ?? [];
+    if (models.length === 0) return [];
+    return [
+      {
+        wire: {
+          id: `${ctx.jobId}:llm`,
+          scheme: "bearer",
+          value: "short-lived-secret",
+          endpoint: "https://llm-gateway.example/v1",
+          constraints: { allowed_models: [...models] },
+        },
+        provisionerId: `${ctx.jobId}:llm`,
+      },
+    ];
+  },
+  async revoke(_provisionerId) {},
+};
+
+const server = new ARCPServer({
+  runtime: { name: "runtime", version: "1.0.0" },
+  capabilities: { encodings: ["json"] },
+  credentialProvisioner: provisioner,
+  credentialStore: new InMemoryCredentialStore(),
+});
+```
+
+`InMemoryCredentialStore` is for tests and local demos. Production
+runtimes should use a durable store so revocation records survive
+process restarts.
+
+## Wire Shape
+
+Each credential has this shape:
+
+```ts
+{
+  id: string;
+  scheme: "bearer";
+  value: string;
+  endpoint: string;
+  profile?: string;
+  constraints?: {
+    expires_at?: string;
+    allowed_models?: string[];
+    max_spend?: { currency: string; amount: number };
+  };
+}
+```
+
+`value` is a secret. The runtime sends it only to the original job
+submitter and omits it from cross-principal subscription views.
+
+## LiteLLM Mapping
+
+LiteLLM is the reference shape for a pluggable provider, but it is not
+built into the SDK:
+
+| ARCP field                         | LiteLLM `/key/generate` field |
+| ---------------------------------- | ----------------------------- |
+| `lease["model.use"]`               | `allowed_models`              |
+| `lease["cost.budget"]`             | `max_budget`                  |
+| `leaseConstraints.expires_at`      | key duration / expiry         |
+| `Credential.provisionerId`         | LiteLLM key alias/id          |
+| `Credential.endpoint`              | LiteLLM proxy base URL        |
+
+Use `toBudgetExhausted(error, details)` in a provisioner or gateway shim
+when the upstream reports a spend-cap failure; it converts the vendor
+failure to ARCP `BUDGET_EXHAUSTED`.

docs/guides/leases.md

@@ -22,6 +22,8 @@ A capability name is `<namespace>:<resource>`. Reserved namespaces:
 | `net.fetch`      | Outbound HTTP/S3/etc. Pattern is a URL glob.           |
 | `tool.call`      | Tool invocation. Pattern matches against `tool` name.  |
 | `agent.delegate` | Spawning child jobs. Pattern matches child agent name. |
+| `model.use`      | LLM model invocation. Pattern matches model id/name.   |
+| `cost.budget`    | Spend cap, encoded as `CURRENCY:amount` patterns.      |
 
 Custom namespaces MUST use `x-vendor.<vendor>.<cap>`:
 
@@ -181,6 +183,31 @@ budget currency, the runtime decrements. Exhaustion throws
 The runtime also emits a `metric` event with name `budget_remaining`
 when consumption crosses 5% deltas (debounced).
 
+## Model Use (v1.1, §9.7)
+
+`model.use` narrows which upstream model ids the job may invoke:
+
+```ts
+const handle = await client.submit({
+  agent: "research",
+  input: {},
+  lease: {
+    "model.use": ["gpt-4*", "claude-3-5-*"],
+    "cost.budget": ["USD:2.00"],
+  },
+});
+```
+
+The runtime treats model ids like other lease targets: `*` and `**`
+are glob wildcards, matching is anchored, and delegation may only
+narrow the model set. For example, a child with `model.use:
+["gpt-4o-mini"]` is a subset of a parent with `["gpt-4*"]`; a child
+with `["**"]` is not.
+
+When a credential provisioner is configured, `model.use` is also the
+source for credential constraints. Provisioners should map these
+patterns to the upstream provider's allowed-model list.
+
 ## Hand-written validation
 
 `validateLeaseShape(lease)` checks structural well-formedness;
@@ -204,4 +231,5 @@ for (const cap of Object.keys(incoming)) {
 - [`examples/lease-violation/`](../../examples/lease-violation/) — denied access surfaces as `tool_result.error`.
 - [`examples/lease-expires-at/`](../../examples/lease-expires-at/) — v1.1 expiration.
 - [`examples/cost-budget/`](../../examples/cost-budget/) — v1.1 budgets.
+- [`examples/provisioned-credentials/`](../../examples/provisioned-credentials/) — v1.1 model-bound credentials.
 - [`examples/delegate/`](../../examples/delegate/) — subset validation on child spawn.

examples/README.md

@@ -31,6 +31,7 @@ real `Transport`. No mocks. No in-memory shortcuts. Each example exits
 | [`agent-versions/`](./agent-versions/)     | `name@version` grammar; default-version resolution for bare names; `AGENT_VERSION_NOT_AVAILABLE` on unregistered version.                                                                            | §7.5, §12  |
 | [`lease-expires-at/`](./lease-expires-at/) | `lease_constraints.expires_at` deadline; agent's `validateLeaseOp` and runtime watchdog both trip `LEASE_EXPIRED`.                                                                                   | §9.5, §12  |
 | [`cost-budget/`](./cost-budget/)           | `cost.budget` lease capability; `cost.*` metrics auto-decrement the counter; runtime emits debounced `cost.budget.remaining`; final call hits `BUDGET_EXHAUSTED`.                                    | §9.6, §12  |
+| [`provisioned-credentials/`](./provisioned-credentials/) | Runtime mints a model-bound bearer credential from `model.use` and revokes it when the job completes. | §9.7, §9.8 |
 | [`progress/`](./progress/)                 | `progress` event kind; client renders a text progress bar.                                                                                                                                           | §8.2.1     |
 | [`result-chunk/`](./result-chunk/)         | `ctx.streamResult()` writes ~30 chunks; terminal `job.result` carries `result_id` + `result_size`; client `handle.collectChunks()` reassembles.                                                      | §8.4       |
 

examples/provisioned-credentials/README.md

@@ -0,0 +1,28 @@
+# provisioned-credentials example (v1.1)
+
+Demonstrates `model.use` plus a runtime-side `CredentialProvisioner`.
+The server mints a deterministic bearer credential for the accepted job,
+echoes it in `job.accepted`, stores only its revocation id, and revokes it
+when the job completes.
+
+## Run
+
+In one terminal:
+
+```sh
+pnpm tsx examples/provisioned-credentials/server.ts
+```
+
+In a second terminal:
+
+```sh
+pnpm tsx examples/provisioned-credentials/client.ts
+```
+
+## What it demonstrates
+
+- §9.7 `model.use` lease capability.
+- §9.8 `CredentialProvisioner` issue/revoke lifecycle.
+- Credential constraints derived from the job lease.
+- Client access via `handle.credentials`.
+

examples/provisioned-credentials/client.ts

@@ -0,0 +1,39 @@
+import { ARCPClient, WebSocketTransport } from "@arcp/sdk";
+
+const URL = process.env.ARCP_DEMO_URL ?? "ws://127.0.0.1:7892";
+const TOKEN = process.env.ARCP_DEMO_TOKEN ?? "demo-token";
+
+async function main(): Promise<void> {
+  const client = new ARCPClient({
+    client: { name: "provisioned-credentials-demo-client", version: "1.0.0" },
+    capabilities: { encodings: ["json"] },
+    authScheme: "bearer",
+    token: TOKEN,
+  });
+
+  const transport = await WebSocketTransport.connect(URL);
+  await client.connect(transport);
+
+  const handle = await client.submit({
+    agent: "ask-model",
+    input: { prompt: "hello" },
+    lease: {
+      "model.use": ["gpt-4o-mini"],
+      "cost.budget": ["USD:0.10"],
+    },
+  });
+
+  const credential = handle.credentials?.[0];
+  process.stdout.write(
+    `accepted job_id=${handle.jobId} credential=${credential?.id ?? "none"} endpoint=${credential?.endpoint ?? "none"}\n`,
+  );
+
+  const result = await handle.done;
+  process.stdout.write(`${JSON.stringify(result.result)}\n`);
+  await client.close();
+}
+
+void main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack : String(err)}\n`);
+  process.exit(1);
+});

examples/provisioned-credentials/server.ts

@@ -0,0 +1,81 @@
+import {
+  ARCPServer,
+  InMemoryCredentialStore,
+  StaticBearerVerifier,
+  startWebSocketServer,
+  type CredentialIssueContext,
+  type CredentialProvisioner,
+  type IssuedCredential,
+} from "@arcp/sdk";
+
+const PORT = Number(process.env.ARCP_DEMO_PORT ?? 7892);
+const TOKEN = process.env.ARCP_DEMO_TOKEN ?? "demo-token";
+
+class MockProvisioner implements CredentialProvisioner {
+  public readonly revoked: string[] = [];
+
+  async issue(ctx: CredentialIssueContext): Promise<IssuedCredential[]> {
+    const models = ctx.lease["model.use"] ?? [];
+    if (models.length === 0) return [];
+    const id = `${ctx.jobId}:mock-llm`;
+    return [
+      {
+        wire: {
+          id,
+          scheme: "bearer",
+          value: `mock-key-${ctx.jobId}`,
+          endpoint: "http://localhost/mock-llm/v1",
+          constraints: {
+            allowed_models: [...models],
+            ...(ctx.leaseConstraints?.expires_at === undefined
+              ? {}
+              : { expires_at: ctx.leaseConstraints.expires_at }),
+          },
+        },
+        provisionerId: id,
+      },
+    ];
+  }
+
+  async revoke(provisionerId: string): Promise<void> {
+    this.revoked.push(provisionerId);
+    process.stdout.write(`revoked ${provisionerId}\n`);
+  }
+}
+
+async function main(): Promise<void> {
+  const server = new ARCPServer({
+    runtime: { name: "provisioned-credentials-demo", version: "1.0.0" },
+    capabilities: {
+      encodings: ["json"],
+      agents: ["ask-model"],
+    },
+    bearer: new StaticBearerVerifier(new Map([[TOKEN, { principal: "demo" }]])),
+    credentialProvisioner: new MockProvisioner(),
+    credentialStore: new InMemoryCredentialStore(),
+  });
+
+  server.registerAgent("ask-model", async (_input, ctx) => {
+    return {
+      modelLease: ctx.lease["model.use"] ?? [],
+    };
+  });
+
+  const ws = await startWebSocketServer({
+    host: "127.0.0.1",
+    port: PORT,
+    onTransport: (t) => {
+      server.accept(t);
+    },
+  });
+  process.stdout.write(`ARCP server listening on ${ws.url}\n`);
+
+  process.on("SIGINT", () => {
+    void ws.close().then(() => server.close());
+  });
+}
+
+void main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack : String(err)}\n`);
+  process.exit(1);
+});

packages/client/src/client-dispatch.ts

@@ -348,6 +348,7 @@ function onJobAccepted(
   inv.agent = payload.agent;
   inv.leaseConstraints = payload.lease_constraints;
   inv.budget = payload.budget;
+  inv.credentials = payload.credentials;
   inv.traceId = payload.trace_id ?? inv.traceId;
   target.invocationsByJobId.set(payload.job_id, inv);
   inv.acceptance.resolve(payload);

packages/client/src/client-handle.ts

@@ -7,6 +7,7 @@ import type {
   Lease,
   LeaseConstraints,
   ResultChunkBody,
+  Credential,
 } from "@arcp/core/messages";
 import type { Deferred } from "@arcp/core/util";
 
@@ -18,6 +19,7 @@ export interface InvocationState {
   agent: string | undefined;
   leaseConstraints: LeaseConstraints | undefined;
   budget: Record<string, number> | undefined;
+  credentials: Credential[] | undefined;
   traceId: TraceId | undefined;
   events: JobEventPayload[];
   acceptance: Deferred<JobAcceptedPayload>;
@@ -43,6 +45,9 @@ export function makeHandleFromInvocation(inv: InvocationState): JobHandle {
     get budget(): Record<string, number> | undefined {
       return inv.budget;
     },
+    get credentials(): readonly Credential[] | undefined {
+      return inv.credentials;
+    },
     get traceId(): TraceId | undefined {
       return inv.traceId;
     },

packages/client/src/client.ts

@@ -361,6 +361,7 @@ export class ARCPClient {
       agent: undefined,
       leaseConstraints: undefined,
       budget: undefined,
+      credentials: undefined,
       traceId: opts.traceId,
       events: [],
       acceptance: new Deferred<JobAcceptedPayload>(),