Implement v1.1 provisioned credentials

Author: nficano

CONFORMANCE.md

@@ -16,7 +16,7 @@ v1.0.0). No spec MUST/SHOULD in §4–§16 is unimplemented.
 | §6.1 Bearer auth scheme | yes | `lib/arcp/auth/bearer.rb` |
 | §6.1 Pluggable AuthScheme | yes | `lib/arcp/auth/auth_scheme.rb` |
 | §6.2 Capability negotiation (intersection) | yes | `lib/arcp/session/capability_set.rb#intersect` |
-| §6.2 Feature names: heartbeat, ack, list_jobs, subscribe, lease_expires_at, cost.budget, progress, result_chunk, agent_versions | yes | `lib/arcp/session/feature.rb` |
+| §6.2 Feature names: heartbeat, ack, list_jobs, subscribe, lease_expires_at, cost.budget, progress, result_chunk, agent_versions, model.use, provisioned_credentials | yes | `lib/arcp/session/feature.rb` |
 | §6.3 session.welcome with resume_token + resume_window_sec | yes | `lib/arcp/session/welcome.rb`, `lib/arcp/runtime/session_actor.rb` |
 | §6.3 Resume by last_event_seq | yes | `lib/arcp/runtime/event_log.rb` |
 | §6.4 session.ping / session.pong heartbeats | yes | `lib/arcp/session/ping.rb`, `lib/arcp/session/pong.rb`, `lib/arcp/client.rb#start_heartbeat!` |
@@ -51,6 +51,9 @@ v1.0.0). No spec MUST/SHOULD in §4–§16 is unimplemented.
 | §9.6 cost.budget capability (BigDecimal per currency) | yes | `lib/arcp/lease.rb#CostBudget` |
 | §9.6 BudgetCounter try_decrement | yes | `lib/arcp/lease.rb#BudgetCounter` |
 | §9.6 BUDGET_EXHAUSTED on overspend | yes | `lib/arcp/runtime/lease_manager.rb` |
+| §9.7 model.use capability and lease checks | yes | `lib/arcp/lease.rb`, `lib/arcp/runtime/lease_manager.rb#check_model!` |
+| §9.8 provisioned credential wire shape | yes | `lib/arcp/credential.rb`, `lib/arcp/job/accepted.rb` |
+| §9.8 credential provisioner and revocation lifecycle | yes | `lib/arcp/credential_provisioner.rb`, `lib/arcp/runtime/credential_registry.rb`, `lib/arcp/runtime/job_manager.rb` |
 | §10 Delegate event kind with child lease | yes | `lib/arcp/job/event_body/delegate.rb` |
 | §10 LEASE_SUBSET_VIOLATION on excess | yes | `lib/arcp/lease.rb#Subsetting.bound` |
 | §11 trace_id propagation on envelope | yes | `lib/arcp/envelope.rb`, `lib/arcp/client.rb#send_envelope` |

docs/concepts/leases.md

@@ -11,7 +11,8 @@ spec_sections: [§9]
 ## What
 
 A lease is the runtime's grant of authority to a job: a set of
-capabilities, an optional expiry, and an optional per-currency budget.
+capabilities, an optional expiry, optional model patterns, and an
+optional per-currency budget.
 The runtime issues one on `job.accepted` and attaches it to the job
 context. Delegation requires the child lease to be a strict subset.
 
@@ -47,13 +48,37 @@ budget.remaining('USD') # => BigDecimal('1.00')
 `BudgetCounter#try_spend!` atomically decrements; overspend raises
 `Arcp::Errors::BudgetExhausted`.
 
+## model.use
+
+```ruby
+lease_request = Arcp::Lease::LeaseRequest.new(
+  capabilities: ['cost.spend'],
+  model_use: ['tier-fast/*']
+)
+```
+
+`model.use` is a set of glob patterns for model ids. Runtime code in the
+path of an LLM call can enforce it with:
+
+```ruby
+$arcp_runtime.lease_manager.check_model!(
+  ctx.job_id,
+  model_id: 'tier-fast/gpt-4o-mini'
+)
+```
+
+A miss raises `Arcp::Errors::PermissionDenied`. Delegate subsetting also
+checks `model.use`; a child may keep the same pattern or narrow a parent
+glob to a literal model id.
+
 ## Subsetting on delegate
 
 ```ruby
 parent = $arcp_runtime.lease_manager.get(ctx.job_id)
 child_request = Arcp::Lease::LeaseRequest.new(
   capabilities: ['compute.read'],
   budget: Arcp::Lease::CostBudget.parse(['USD:0.25']),
+  model_use: ['tier-fast/gpt-4o-mini'],
   expires_at: nil
 )
 child = Arcp::Lease::Subsetting.bound(parent: parent, request: child_request)
@@ -66,3 +91,4 @@ above parent's remaining all raise `Arcp::Errors::LeaseSubsetViolation`.
 
 - `concepts/delegation.md`
 - `guides/budgets.md`
+- `guides/credentials.md`

docs/guides/budgets.md

@@ -46,6 +46,10 @@ end
 balance goes negative, the runtime emits `job.error` with code
 `BUDGET_EXHAUSTED`.
 
+When spend is enforced by an upstream gateway instead of local counters,
+configure provisioned credentials so `cost.budget` is baked into the issued
+key. See `docs/guides/credentials.md`.
+
 ## Client-side exhaustion
 
 ```ruby

docs/guides/credentials.md

@@ -0,0 +1,122 @@
+---
+title: Provisioned credentials
+sdk: ruby
+kind: guide
+order: 22
+spec_sections: [§9.7, §9.8]
+---
+
+# Provisioned credentials
+
+Provisioned credentials let a runtime mint short-lived upstream keys for a
+job after the lease is finalized. The key is returned only on
+`job.accepted`, scoped by the lease, and revoked when the job terminates.
+
+## Configure the runtime
+
+```ruby
+provisioner = Arcp::Credentials::InMemoryProvisioner.new(
+  endpoint: 'https://llm-gateway.example/v1',
+  profile: 'openai'
+)
+
+runtime = Arcp::Runtime::Runtime.new(
+  auth_verifier: auth,
+  credential_provisioner: provisioner,
+  credential_store: Arcp::Credentials::InMemoryStore.new
+)
+```
+
+When a provisioner is configured, the runtime advertises the
+`model.use` and `provisioned_credentials` features during capability
+negotiation. Without a provisioner, both features are omitted.
+
+## Request model access
+
+```ruby
+handle = client.submit_job(
+  agent: 'gateway-caller',
+  lease_request: Arcp::Lease::LeaseRequest.new(
+    capabilities: ['cost.spend'],
+    budget: Arcp::Lease::CostBudget.parse(['USD:1.00']),
+    model_use: ['tier-fast/*']
+  )
+)
+
+credential = handle.credential_for(endpoint: 'https://llm-gateway.example/v1')
+```
+
+The runtime copies `cost.budget`, `model.use`, and `expires_at` into the
+credential constraints so an upstream gateway can enforce the same bounds.
+
+## Implement a provisioner
+
+```ruby
+class LiteLLMProvisioner
+  include Arcp::CredentialProvisioner
+
+  def issue(lease:, job_id:, agent:, principal_id:)
+    response = generate_litellm_key(
+      budget: lease.budget&.to_a,
+      models: lease.model_use,
+      expires_at: lease.expires_at
+    )
+
+    [
+      Arcp::Credential.new(
+        id: response.fetch('key_alias'),
+        scheme: Arcp::Credential::SCHEME_BEARER,
+        value: response.fetch('key'),
+        endpoint: 'https://llm-gateway.example/v1',
+        profile: 'openai',
+        constraints: {
+          'cost.budget' => lease.budget&.to_a,
+          'model.use' => lease.model_use,
+          'expires_at' => lease.expires_at
+        }.compact
+      )
+    ]
+  end
+
+  def revoke(credential_id:)
+    delete_litellm_key(credential_id)
+  end
+end
+```
+
+Vendor-specific HTTP clients should live outside the core gem. The SDK only
+defines the interface and value objects.
+
+When an upstream gateway reports budget exhaustion, map it back to the ARCP
+error boundary:
+
+```ruby
+begin
+  call_gateway(credential)
+rescue StandardError => e
+  raise Arcp::Credentials.translate_upstream_error(e)
+end
+```
+
+## Rotation and revocation
+
+Agents can rotate a credential value mid-job:
+
+```ruby
+ctx.rotate_credential(id: 'cred_job_123_0', new_value: 'sk-new-value')
+```
+
+That emits a `status` event with `phase: 'credential_rotated'` and a
+`fields` hash containing the new `{ id, value }`. Treat this event as
+secret-bearing data.
+
+The runtime revokes outstanding credential ids on success, error,
+cancellation, and timeout. `CredentialRegistry` retries transient revoke
+failures once and keeps any failed id in the configured store for later
+reconciliation.
+
+## Security notes
+
+`Credential#to_h` is the wire representation and includes `value`.
+Use `Credential#to_redacted_h` for logs, metrics, and examples.
+`session.list_jobs` summaries never include credentials.

lib/arcp.rb

@@ -9,6 +9,8 @@
 require_relative 'arcp/envelope'
 require_relative 'arcp/trace'
 require_relative 'arcp/lease'
+require_relative 'arcp/credential'
+require_relative 'arcp/credential_provisioner'
 require_relative 'arcp/session'
 require_relative 'arcp/job'
 require_relative 'arcp/auth'

lib/arcp/client.rb

@@ -140,7 +140,9 @@ def submit_job(agent:, input: nil, lease_request: nil, lease_constraints: nil,
       accepted = Arcp::Job::Accepted.from_h(accepted_env.payload)
       Arcp::Job::Handle.new(
         job_id: accepted.job_id, agent: accepted.agent,
-        submitted_at: accepted.accepted_at, lease: accepted.lease
+        submitted_at: accepted.accepted_at,
+        lease: accepted.lease,
+        credentials: accepted.credentials
       )
     end
 

lib/arcp/credential.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Arcp
+  Credential = Data.define(:id, :scheme, :value, :endpoint, :profile, :constraints) do
+    def initialize(id:, scheme:, value:, endpoint:, profile: nil, constraints: nil)
+      super(
+        id: id,
+        scheme: scheme,
+        value: value,
+        endpoint: endpoint,
+        profile: profile,
+        constraints: constraints || {}
+      )
+    end
+
+    def self.from_h(h)
+      h = h.transform_keys(&:to_s)
+      new(
+        id: h.fetch('id'),
+        scheme: h.fetch('scheme'),
+        value: h.fetch('value'),
+        endpoint: h.fetch('endpoint'),
+        profile: h['profile'],
+        constraints: h['constraints'] || {}
+      )
+    end
+
+    def to_h
+      out = { 'id' => id, 'scheme' => scheme, 'value' => value, 'endpoint' => endpoint }
+      out['profile'] = profile if profile
+      out['constraints'] = constraints if constraints && !constraints.empty?
+      out
+    end
+
+    def to_redacted_h
+      to_h.merge('value' => '[REDACTED]')
+    end
+  end
+
+  Credential.const_set(:SCHEME_BEARER, 'bearer') unless Credential.const_defined?(:SCHEME_BEARER)
+
+  module ModelPattern
+    FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    module_function
+
+    def match?(patterns, model_id)
+      Array(patterns).any? { |pattern| File.fnmatch?(pattern, model_id, FLAGS) }
+    end
+
+    def implied_by?(parent_patterns, child_pattern)
+      Array(parent_patterns).any? do |parent|
+        child_pattern == parent || literal_match?(parent, child_pattern)
+      end
+    end
+
+    def literal_match?(parent_pattern, child_pattern)
+      !glob?(child_pattern) && match?([parent_pattern], child_pattern)
+    end
+
+    def glob?(pattern)
+      pattern.match?(/[*?\[\]{}]/)
+    end
+  end
+end