knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/route_refusal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module KnoxCall
+  # The route-mode REFUSAL predicate (PARITY §21.1, "Refusal-driven refresh";
+  # the cross-language contract is sdk/fixtures/route-refusal.json).
+  #
+  # A KnoxCall-origin refusal on the route data plane is the one response the
+  # pipeline answers by refreshing its manifest ONCE and re-deciding ONCE:
+  #
+  #   - a 401 with no upstream stamp — the credential was refused, or the caller
+  #     is not authenticated for the route it named. +call+ has already spent its
+  #     one re-mint by the time we see this.
+  #   - a 404 whose envelope +error.type+ is +route_not_found+ — since the
+  #     founder's 2026-09-26 decision an AUTHENTICATED key gets a real 404 for a
+  #     route that does not resolve, and a stale manifest naming a Route deleted
+  #     since the poll is exactly this. The +environment_*+ types are refused
+  #     as-is: a refresh cannot fix an environment.
+  #
+  # Any response carrying +X-Knox-Upstream-Status+ (the route data plane's
+  # response block) or +X-Knox-Destination-Status+ (the ephemeral proxy's older
+  # spelling) is the UPSTREAM's answer, whatever its status or body, and never a
+  # refusal.
+  module RouteRefusal
+    module_function
+
+    # @param status [Integer]
+    # @param headers [Hash] raw response headers, any casing; values may be
+    #   strings or arrays (Net::HTTPResponse#to_hash yields arrays)
+    # @param body [String, nil]
+    def refusal?(status:, headers:, body:)
+      return false if header(headers, "X-Knox-Upstream-Status") || header(headers, "X-Knox-Destination-Status")
+      return true if status == 401
+      return false unless status == 404
+
+      envelope_type(body) == "route_not_found"
+    end
+
+    # The envelope's +error.type+ on a 404, or nil for anything that is not the
+    # Shape-A envelope +{"error":{"type","message","request_id"}}+.
+    def envelope_type(body)
+      return nil if body.nil? || body.empty?
+
+      parsed = JSON.parse(body)
+      return nil unless parsed.is_a?(Hash)
+
+      error = parsed["error"]
+      return nil unless error.is_a?(Hash)
+
+      type = error["type"]
+      type.is_a?(String) ? type : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    def header(headers, name)
+      pair = headers.find { |k, _| k.to_s.casecmp(name).zero? }
+      return nil unless pair
+
+      v = pair.last
+      v = v.first if v.is_a?(Array)
+      v = v.to_s
+      v.empty? ? nil : v
+    end
+  end
+end

data/lib/knoxcall/signup.rb

@@ -0,0 +1,122 @@
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+
+module KnoxCall
+  # Headless signup — the one /v1 surface that needs no credentials, so these
+  # are module-level functions rather than resources on a constructed client.
+  #
+  # TWO steps since 2026-08-28 (founder decision F-25). +signup+ never returns
+  # a credential: it returns a claim handle and emails a sign-in link, and the
+  # starter key is minted when that link has been clicked and the claim is
+  # collected:
+  #
+  #   accepted = KnoxCall.signup({ email: "dev@example.com", tenant_name: "Acme Inc" })
+  #   handle   = accepted["claim_handle"]
+  #
+  #   # …the account owner clicks the emailed sign-in link…
+  #   claim = KnoxCall.claim_signup(handle)
+  #   while claim["status"] == "pending"
+  #     sleep accepted["poll_after_seconds"]
+  #     claim = KnoxCall.claim_signup(handle)
+  #   end
+  #
+  #   # claim["starter"]["api_key"]["api_key"] is shown exactly once — store it now.
+  #   client = KnoxCall::Client.new(api_key: claim["starter"]["api_key"]["api_key"], sandbox: true)
+
+  # The shared credential-less POST. Note what it does NOT treat as an error:
+  # a 202. Both endpoints use it for a normal, credential-less success, so any
+  # sub-400 response carrying a +data+ object is returned unchanged.
+  #
+  # @api private
+  def self._signup_post(path, payload, what, base_url, timeout)
+    uri = URI.parse((base_url || DEFAULT_API_BASE).chomp("/") + path)
+    req = Net::HTTP::Post.new(uri)
+    req["Content-Type"] = "application/json"
+    req["Accept"] = "application/json"
+    req["User-Agent"] = SDK_VERSION
+    req.body = JSON.generate(payload)
+
+    resp = begin
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.start { |h| h.request(req) }
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ConnectionTimeoutError, "#{what} request timed out: #{e.message}"
+    rescue OpenSSL::SSL::SSLError, EOFError, SocketError, SystemCallError, IOError => e
+      raise NetworkError, "#{what} request failed: #{e.class}: #{e.message}"
+    end
+
+    parsed = begin
+      JSON.parse(resp.body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+    status = resp.code.to_i
+    data = parsed.is_a?(Hash) && parsed["data"].is_a?(Hash) ? parsed["data"] : nil
+    if status >= 400 || data.nil?
+      err = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : {}
+      message = err["message"].is_a?(String) ? err["message"] : "#{what} failed with status #{status}"
+      request_id = err["request_id"] || resp["x-request-id"]
+      raise SignupError.new(
+        message,
+        status_code: status,
+        error_type: err["type"].is_a?(String) ? err["type"] : nil,
+        request_id: request_id.is_a?(String) ? request_id : nil,
+        body: parsed
+      )
+    end
+    data
+  end
+
+  # Start creating a KnoxCall account.
+  #
+  # Always answers 202 with an opaque +claim_handle+ and emails a sign-in link
+  # — no account, tenant or credential exists until that link is clicked.
+  # Collect the starter kit afterwards with {claim_signup}. Rate limited to 3
+  # signups/hour/IP.
+  #
+  # Enumeration-safe: the reply is identical for an address that already has an
+  # account (it receives a sign-in link and a handle that stays "pending").
+  #
+  # +input+ fields: +email+ (required), +tenant_name+ (required), +full_name+,
+  # +tenant_slug+ (omit to have one derived — recommended), +country+,
+  # +region+ ("us"|"eu"|"au").
+  #
+  # @param input [Hash] the signup fields (symbol or string keys)
+  # @param base_url [String, nil] management API base (default https://api.knoxcall.com)
+  # @param timeout [Numeric] open/read timeout in seconds (default 30)
+  # @return [Hash] +status+, +claim_handle+, +claim_path+, +poll_after_seconds+,
+  #   +expires_at+, +message+, +documentation+ — and never a credential
+  # @raise [SignupError] on any HTTP failure or unexpected body — carries
+  #   +status_code+, +error_type+ (e.g. "slug_taken"), +request_id+
+  # @raise [NetworkError, ConnectionTimeoutError] on transport failure
+  def self.signup(input, base_url: nil, timeout: 30)
+    _signup_post("/v1/signup", input, "Signup", base_url, timeout)
+  end
+
+  # Poll a claim handle returned by {signup}.
+  #
+  # Returns <tt>{"status" => "pending", ...}</tt> — a 202, and a normal SUCCESS
+  # — until the emailed sign-in link has been clicked, then once returns
+  # <tt>{"status" => "ready", ...}</tt> with the tenant and a one-time
+  # Test-mode API key. Polling again after that raises {SignupError} (409); an
+  # unknown or expired handle raises it with 404.
+  #
+  # Do not poll faster than the +poll_after_seconds+ that {signup} returned.
+  #
+  # @param claim_handle [String] the handle returned by {signup}
+  # @param base_url [String, nil] management API base (default https://api.knoxcall.com)
+  # @param timeout [Numeric] open/read timeout in seconds (default 30)
+  # @return [Hash] +status+ plus either the pending fields or +tenant+,
+  #   +starter+, +sandbox+, +documentation+
+  # @raise [SignupError] 404 unknown/expired, 409 already collected, or any
+  #   other HTTP failure
+  # @raise [NetworkError, ConnectionTimeoutError] on transport failure
+  def self.claim_signup(claim_handle, base_url: nil, timeout: 30)
+    _signup_post("/v1/signup/claim", { claim_handle: claim_handle }, "Signup claim", base_url, timeout)
+  end
+end

data/lib/knoxcall/token_exchange.rb

@@ -0,0 +1,169 @@
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+
+require "knoxcall/warnings"
+
+module KnoxCall
+  # The only grant_type POST /v1/oauth/token accepts.
+  TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange".freeze
+  # The only subject_token_type it accepts.
+  ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token".freeze
+  # The default (and only supported) audience.
+  KNOXCALL_AUDIENCE = "knoxcall:gateway".freeze
+
+  # Exchange a CI OIDC token for a short-lived AI-gateway capability token
+  # (RFC 8693 token exchange, AIGW-26).
+  #
+  #   res = KnoxCall.exchange_token(subject_token: ci_id_token, tenant: "acme")
+  #   # res["access_token"] is an agent-kind token for POST /v1/ai/...
+  #
+  # Like KnoxCall.signup this is a module-level function and NOT a method on a
+  # constructed client, and for a stronger reason: the whole point is that CI
+  # holds no KnoxCall credential. Constructing a client to reach this endpoint
+  # would require the very secret the flow exists to remove — so NO
+  # Authorization header is sent. The subject_token IS the credential, verified
+  # against the issuer's published JWKS.
+  #
+  # Pass +resource+ — the +resource+ field of an MCP server's create/get
+  # response — to narrow the minted token to +tool+ kind, confined to exactly
+  # that one <tt>/v1/mcp/<slug></tt> and refused on <tt>/v1/ai</tt>. Leave it
+  # +nil+ (the default) for an +agent+-kind token: an EMPTY STRING is sent
+  # through and refused +invalid_target+, because dropping it silently would
+  # mint an UNCONFINED token while the caller believes it is
+  # audience-restricted.
+  #
+  # THE HOST MATTERS, and getting it wrong looks like a credential failure.
+  # <tt>/v1/oauth/token</tt> is part of the DATA plane: +src/server.ts+ hands
+  # <tt>/v1/ai/</tt>, <tt>/v1/mcp/</tt> and <tt>/v1/oauth/</tt> to the proxy
+  # router only when the request lands on a tenant data-plane host
+  # (<tt>{slug}.knoxcall.com</tt>, <tt>sandbox-{slug}...</tt>). Verified against a
+  # running server on 2026-08-25: the same request answers 400 +invalid_grant+ on
+  # +acme.knoxcall.com+ and *401* on +api.knoxcall.com+ - a caller who points this
+  # at the management host reads that 401 as "my CI token was rejected" when the
+  # endpoint is simply not served there. So +tenant+ (or an explicit +base_url+)
+  # is REQUIRED: there is no safe default to guess.
+  #
+  # NOT the tenant OAuth 2.1 token endpoint at
+  # <tt>https://api.knoxcall.com/oauth/token</tt> (root host, no +/v1+), which
+  # mints +kc_+ MANAGEMENT tokens from +client_credentials+ and friends.
+  #
+  # Returns the RFC 8693 §2.2.1 body — +access_token+, +issued_token_type+,
+  # +token_type+, +expires_in+, +scope+. A BARE OAuth body, not the
+  # <tt>{data, meta}</tt> envelope the rest of /v1 returns.
+  #
+  # @param subject_token [String] the workload's OIDC id_token, JWS-compact
+  # @param resource [String, nil] RFC 8707 resource indicator; nil to omit
+  # @param audience [String] defaults to KNOXCALL_AUDIENCE
+  # @param tenant [String, nil] tenant slug; becomes https://{tenant}.knoxcall.com
+  # @param sandbox [Boolean] use https://sandbox-{tenant}.knoxcall.com
+  # @param base_url [String, nil] full data-plane origin; wins over +tenant+
+  # @param timeout [Numeric] open/read timeout in seconds (default 30)
+  # @return [Hash] the RFC 8693 response body
+  # @raise [TokenExchangeError] on any refusal — carries +status_code+ and
+  #   +error_type+ (the RFC 6749 §5.2 code)
+  # @raise [ArgumentError] when neither +tenant+ nor +base_url+ is given, or the
+  #   tenant slug is not a DNS label
+  # @raise [NetworkError, ConnectionTimeoutError] on transport failure
+  def self.exchange_token(subject_token:, resource: nil, audience: KNOXCALL_AUDIENCE,
+                          tenant: nil, sandbox: false, base_url: nil, timeout: 30)
+    origin = exchange_base_url(tenant, sandbox, base_url)
+    # the request carries the workload OIDC id_token, which IS a credential -- the
+    # whole point of the flow. PARITY 15 already warns when a CLIENT is constructed
+    # against plaintext http to a non-loopback host, and this function deliberately
+    # constructs no client, so without this the control exists on one path and is
+    # simply absent on the parallel one. A warning rather than a refusal because the
+    # acceptance harness and local dev legitimately use http://127.0.0.1.
+    if Warnings.insecure_remote_url?(origin)
+      Warnings.warn_once(
+        "KNOXCALL_INSECURE_TRANSPORT",
+        "KnoxCall: exchanging a workload OIDC token over plaintext HTTP to #{origin} - the " \
+        "subject token is a credential and is readable on the wire. Use https://."
+      )
+    end
+    uri = URI.parse(origin + "/v1/oauth/token")
+    payload = {
+      "grant_type" => TOKEN_EXCHANGE_GRANT,
+      "subject_token" => subject_token,
+      "subject_token_type" => ID_TOKEN_TYPE,
+      "audience" => audience
+    }
+    payload["resource"] = resource unless resource.nil?
+
+    req = Net::HTTP::Post.new(uri)
+    req["Content-Type"] = "application/json"
+    req["Accept"] = "application/json"
+    req["User-Agent"] = SDK_VERSION
+    req.body = JSON.generate(payload)
+
+    resp = begin
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.start { |h| h.request(req) }
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ConnectionTimeoutError, "token exchange timed out: #{e.message}"
+    rescue OpenSSL::SSL::SSLError, EOFError, SocketError, SystemCallError, IOError => e
+      raise NetworkError, "token exchange failed: #{e.class}: #{e.message}"
+    end
+
+    # A non-JSON error page (a proxy 502) parses to nil and falls through to
+    # the status check rather than masking the status.
+    parsed = begin
+      JSON.parse(resp.body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+    status = resp.code.to_i
+    token = parsed.is_a?(Hash) && parsed["access_token"].is_a?(String) ? parsed["access_token"] : nil
+
+    if status >= 400 || token.nil? || token.empty?
+      # AIGW-163: this endpoint is on the TENANT DATA PLANE, so when the AI
+      # gateway has failed to boot it is answered by the plane's 503 sentinel —
+      # the data-plane envelope with code "ai_gateway_unavailable" and a
+      # Retry-After — not by an RFC 6749 error. Typing it means a CI job is told
+      # to wait rather than handed a generic exchange failure. The discriminator
+      # is exact: an RFC 6749 body carries no `code` at all.
+      ai_err = KnoxCall.ai_gateway_error_from(status, parsed, resp)
+      raise ai_err if ai_err
+
+      code = parsed.is_a?(Hash) && parsed["error"].is_a?(String) ? parsed["error"] : "token_exchange_failed"
+      message = if parsed.is_a?(Hash) && parsed["error_description"].is_a?(String)
+                  parsed["error_description"]
+                else
+                  "Token exchange failed with status #{status}"
+                end
+      raise TokenExchangeError.new(message, status_code: status, error_type: code, body: parsed)
+    end
+    parsed
+  end
+
+  # A tenant slug becomes a hostname, so it must be a bare DNS label: a slug
+  # adopted from config or an environment variable that is not one
+  # ("evil.com#") would send the workload OIDC token to an attacker host.
+  TENANT_SLUG_RE = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/i.freeze
+
+  # The data-plane origin for {exchange_token}. There is no default.
+  def self.exchange_base_url(tenant, sandbox, base_url)
+    return base_url.chomp("/") if base_url && !base_url.empty?
+
+    if tenant.nil? || tenant.empty?
+      raise ArgumentError,
+            "exchange_token needs a tenant slug or a base_url: POST /v1/oauth/token is " \
+            "served only on the tenant data-plane host " \
+            "(https://{tenant}.knoxcall.com). Pointing it at api.knoxcall.com answers " \
+            "401, which reads like a rejected subject_token but means the endpoint is " \
+            "not there."
+    end
+    unless TENANT_SLUG_RE.match?(tenant)
+      raise ArgumentError,
+            "invalid tenant slug #{tenant.inspect} - expected a DNS label; refusing to " \
+            "send a subject token to a host derived from it"
+    end
+
+    host = sandbox ? "sandbox-#{tenant}" : tenant
+    "https://#{host}.knoxcall.com"
+  end
+end

data/lib/knoxcall/ulid.rb

@@ -0,0 +1,19 @@
+require "securerandom"
+
+module KnoxCall
+  # ULID generator (Crockford base32: 48-bit timestamp + 80 bits of
+  # randomness). Used for X-Idempotency-Key — generated once per logical
+  # mutating request and stable across retries.
+  module ULID
+    ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ".freeze
+
+    def self.generate(time = Time.now)
+      ms = (time.to_f * 1000).to_i
+      out = +""
+      9.downto(0) { |i| out << ENCODING[(ms >> (i * 5)) & 0x1F] }
+      rand = SecureRandom.random_number(2**80)
+      15.downto(0) { |i| out << ENCODING[(rand >> (i * 5)) & 0x1F] }
+      out
+    end
+  end
+end

data/lib/knoxcall/warnings.rb

@@ -0,0 +1,63 @@
+require "uri"
+
+module KnoxCall
+  # One-time, deduplicated warnings for security-relevant misconfigurations
+  # (plaintext transport, world-readable credentials file). Cross-SDK parity
+  # with node's warn.ts (PARITY §15): each distinct code fires at most once per
+  # process, and the warning is NON-BLOCKING — it never raises and never
+  # changes behavior. Messages go to $stderr via Kernel#warn, so they honor
+  # `-W0` / a replaced `$stderr` and are trivial to capture in tests.
+  module Warnings
+    # Per-process dedup of already-emitted warning codes. A Mutex guards the
+    # check-then-set so concurrent client construction across threads can never
+    # double-warn (or lose a warning).
+    @warned = {}
+    @warned_mutex = Mutex.new
+
+    module_function
+
+    # Test-only: clear the once-per-process dedup so warnings can be re-asserted.
+    def _reset_for_tests
+      @warned_mutex.synchronize { @warned.clear }
+    end
+
+    # Emit +message+ to $stderr at most once per distinct +code+ per process.
+    # The Kernel#warn call happens OUTSIDE the mutex (no I/O under the lock) and
+    # is wrapped so a warning can never throw into the caller's path.
+    def warn_once(code, message)
+      @warned_mutex.synchronize do
+        return if @warned.key?(code)
+        @warned[code] = true
+      end
+      begin
+        warn(message)
+      rescue StandardError
+        # A misconfiguration warning must never break construction or a read.
+      end
+    end
+
+    # True for a URL whose scheme is plaintext http:// and whose host is NOT
+    # loopback. Loopback (localhost, *.localhost, 127.0.0.0/8, ::1, 0.0.0.0) is
+    # the normal local-dev case and must NOT warn; every other host over plain
+    # http:// sends credentials/tokens in the clear.
+    def insecure_remote_url?(url)
+      return false unless url.is_a?(String) && url.match?(%r{\Ahttp://}i)
+      host = begin
+        URI.parse(url).host
+      rescue URI::InvalidURIError
+        nil
+      end
+      return false if host.nil? || host.empty?
+      host = host.downcase
+      # URI#host keeps an IPv6 literal bracketed ("[::1]") — strip for the match.
+      host = host[1..-2] if host.start_with?("[") && host.end_with?("]")
+      loopback =
+        host == "localhost" ||
+        host.end_with?(".localhost") ||
+        host == "0.0.0.0" ||
+        host == "::1" ||
+        host.match?(/\A127\./)
+      !loopback
+    end
+  end
+end

data/lib/knoxcall/workload_provider.rb

@@ -0,0 +1,192 @@
+require "digest"
+require "knoxcall/errors"
+require "knoxcall/token_exchange"
+require "knoxcall/warnings"
+
+module KnoxCall
+  # Workload-identity credential provider — WIF plan Phase 4.3.
+  #
+  # Mirrors +auth/workload-provider.ts+ in the Node SDK; +sdk/PARITY.md+ is the
+  # authoritative contract for every language.
+  #
+  # {KnoxCall.exchange_token} is one-shot: it trades one OIDC assertion for one
+  # capability token and hands the caller an +expires_in+ to manage. That is
+  # fine for a script that makes one call and exits, and wrong for anything
+  # long-lived — a Sidekiq worker, a long CI job, an agent process — where the
+  # token silently expires mid-run and the caller discovers it as a 401 they
+  # then have to interpret.
+  #
+  # This provider owns that lifecycle: cache the token, refresh it before it
+  # dies, and never hand out one that is about to expire.
+  #
+  # == The part that is not like other refresh loops
+  #
+  # A KnoxCall workload assertion is SINGLE-USE. The exchange spends the whole
+  # assertion — the server claims a hash of it before minting (WIF Phase 1.2),
+  # so presenting the same bytes twice is refused with "subject_token has
+  # already been exchanged". A refresh therefore cannot re-send the assertion it
+  # used last time; it needs a FRESH one from the platform every single time.
+  #
+  # That makes the obvious implementation — capture the assertion once, reuse it
+  # on refresh — not merely suboptimal but broken, and broken in a way that only
+  # shows up when the first refresh fires, i.e. minutes into production rather
+  # than in anyone's smoke test. So the provider takes a SOURCE it calls before
+  # every exchange, and refuses to send an assertion whose bytes it has already
+  # spent ({StaleAssertionError}). It fails loudly at the real cause rather than
+  # forwarding a doomed request and surfacing the server's replay refusal, which
+  # reads as "my credentials were rejected".
+  #
+  # == The two-tier schedule
+  #
+  # ADVISORY (expiry − 120s): refresh opportunistically. If it fails, the token
+  # in hand is still valid, so the caller is served and the failure is a
+  # warning, not an exception. A transient blip near a refresh boundary must not
+  # take down a worker that has two minutes of perfectly good credential left.
+  #
+  # MANDATORY (expiry − 30s): refresh or raise. Below this line the token may
+  # die in flight — between the provider handing it over and the request
+  # reaching the server — and a 401 from an expired capability token is exactly
+  # the confusing failure this provider exists to prevent.
+  #
+  # The gap between the two tiers is the whole point: it buys 90 seconds in
+  # which a failing token source or a flaky network is survivable rather than
+  # fatal.
+  #
+  #   provider = KnoxCall::WorkloadCredentialProvider.new(
+  #     assertion: -> { File.read(ENV.fetch("AWS_WEB_IDENTITY_TOKEN_FILE")) },
+  #     tenant: "acme"
+  #   )
+  #   headers["Authorization"] = "Bearer #{provider.access_token}"
+  #
+  # Thread-safe: a Mutex gives single-flight semantics, which matters more here
+  # than in an ordinary refresh loop — each exchange spends an assertion, and a
+  # thundering herd would burn N of them and have N−1 refused.
+  class WorkloadCredentialProvider
+    # Refresh opportunistically below this much remaining life; failure is survivable.
+    ADVISORY_REFRESH_SECONDS = 120
+
+    # Refresh or raise below this much remaining life; the token may die in flight.
+    MANDATORY_REFRESH_SECONDS = 30
+
+    # @param assertion [#call] called before EVERY exchange; must return a FRESH
+    #   assertion each time. On GitHub Actions a fetch of
+    #   ACTIONS_ID_TOKEN_REQUEST_URL; on EKS a read of the projected token file.
+    #   Returning a value captured once at startup is the failure this provider
+    #   detects rather than tolerates.
+    # @param resource [String, nil] RFC 8707 resource indicator. +nil+ means
+    #   "not asked for"; an EMPTY string is sent through and refused
+    #   invalid_target, because dropping it silently would mint an UNCONFINED
+    #   token while the caller believes it is confined.
+    # @param audience [String] defaults to KNOXCALL_AUDIENCE
+    # @param tenant [String, nil] tenant slug — one of tenant or base_url is
+    #   REQUIRED: +/v1/oauth/token+ is served only on the tenant data-plane host.
+    # @param sandbox [Boolean] the Test data space. Carried through verbatim:
+    #   dropping it would send a Test-mode workload's assertion to the Live
+    #   host, where it matches no binding.
+    # @param base_url [String, nil] full data-plane origin; wins over tenant
+    # @param timeout [Integer] per-request timeout in seconds
+    # @param clock [#call] test seam returning epoch seconds as a Float
+    def initialize(assertion:, resource: nil, audience: KNOXCALL_AUDIENCE,
+                   tenant: nil, sandbox: false, base_url: nil, timeout: 30,
+                   clock: -> { Time.now.to_f })
+      unless assertion.respond_to?(:call)
+        raise ArgumentError, "WorkloadCredentialProvider needs an `assertion:` that responds to " \
+                             "#call and returns the workload's CURRENT OIDC id_token. KnoxCall " \
+                             "assertions are single-use, so it is called before every exchange."
+      end
+      # Fail at construction rather than at the first refresh, which may be
+      # minutes into a long-running process.
+      KnoxCall.exchange_base_url(tenant, sandbox, base_url)
+
+      @assertion = assertion
+      @resource = resource
+      @audience = audience
+      @tenant = tenant
+      @sandbox = sandbox
+      @base_url = base_url
+      @timeout = timeout
+      @clock = clock
+      @mutex = Mutex.new
+      @token = nil
+      @expires_at = 0.0
+      # SHA-256 of every assertion this provider has spent. Never the assertion.
+      @spent = {}
+    end
+
+    # A capability token with more than MANDATORY_REFRESH_SECONDS of life left.
+    #
+    # @return [String] the capability token
+    # @raise [StaleAssertionError] when the source returns spent or empty bytes
+    # @raise [TokenExchangeError] on a refusal inside the mandatory window
+    # @raise [NetworkError] on a transport failure inside the mandatory window
+    def access_token
+      @mutex.synchronize do
+        remaining = @token ? @expires_at - @clock.call : -1.0
+
+        return @token if @token && remaining > ADVISORY_REFRESH_SECONDS
+
+        if @token && remaining > MANDATORY_REFRESH_SECONDS
+          # ADVISORY tier: try, but the token in hand is still good.
+          begin
+            return refresh
+          rescue StandardError => e
+            # best-effort: the caller still has a valid credential, and raising
+            # here would convert a survivable blip into an outage. The MANDATORY
+            # tier raises for real if the condition persists.
+            Warnings.warn_once(
+              "KNOXCALL_WORKLOAD_ADVISORY_REFRESH",
+              "KnoxCall: advisory token refresh failed (#{e.message}); continuing with the " \
+              "current token, which expires in #{remaining.round}s"
+            )
+            return @token
+          end
+        end
+
+        # MANDATORY tier, or nothing cached at all.
+        refresh
+      end
+    end
+
+    private
+
+    # Exchange a fresh assertion. Called with @mutex held, which is what makes
+    # the exchange single-flight.
+    def refresh
+      assertion = @assertion.call
+      unless assertion.is_a?(String) && !assertion.empty?
+        raise StaleAssertionError, "the workload assertion source returned nothing. It must " \
+                                   "return the workload's current OIDC id_token on every call."
+      end
+
+      fingerprint = Digest::SHA256.hexdigest(assertion)
+      if @spent.key?(fingerprint)
+        raise StaleAssertionError,
+              "the workload assertion source returned an assertion that has already been " \
+              "exchanged. KnoxCall assertions are single-use, so each refresh needs a NEWLY " \
+              "minted one — call the platform's token endpoint inside the source (for example " \
+              "re-fetch ACTIONS_ID_TOKEN_REQUEST_URL, or re-read the projected service-account " \
+              "token file) rather than capturing one value at startup."
+      end
+
+      res = KnoxCall.exchange_token(
+        subject_token: assertion,
+        resource: @resource,
+        audience: @audience,
+        tenant: @tenant,
+        sandbox: @sandbox,
+        base_url: @base_url,
+        timeout: @timeout
+      )
+
+      # Recorded only after the exchange returns, so a network failure does not
+      # burn a fingerprint the caller could legitimately retry with. The server
+      # claims the assertion before it mints, so a SUCCESS is what makes those
+      # bytes unusable.
+      @spent[fingerprint] = true
+
+      @token = res["access_token"]
+      @expires_at = @clock.call + res["expires_in"].to_f
+      @token
+    end
+  end
+end