agentadmit 1.9.0 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 677087b98e731945e7485c16db8c8a858dabc54fa346565b3697948db26f9fcb
-  data.tar.gz: 189ff20ab78520f0ae0ce4a7db1cd32ba8067153c5c5787f4cd04984730eece3
+  metadata.gz: 305d2a2680095a277efd613bbc48dc1c0e948109f05ce01aa995dbff99c172bc
+  data.tar.gz: 559cae430ea15ea9c66fb7e758efdab50fa652625d67f31bf7dab06d4606842d
 SHA512:
-  metadata.gz: 4e374766292936272c50ca95fd2b63ae97f5cb044d194a879dc268009e453630406e090fb57227dcb3dc19f964a04ec3c12dd7b40500cbfd1f1f6b218771e7cc
-  data.tar.gz: c18398441c0d63526cb6fce609907eea627830a7dc71803688542a29950d8b0cf7ed1bd9d30dc3c0be3c154f53ba4f568707b855c3e01e001f5cdbc7ed9a1ff6
+  metadata.gz: 145b55beeabfec1d0860f8d2bdf772b28e2a4a8ca0926c814aac49c3f516bee31f1a66f4dd26c894803452a178bfd296083ec89143185e4c3925aa8d4ae7ac07
+  data.tar.gz: f1e2e43b3ea29c1f59a67d2b8791050d8058cac7210edac2cab8b9ef5f6915b35e91479d30ea3cd44709b1ccaaab16c855dc38851f8aab0ce567e1a693b7914f

data/README.md

@@ -368,3 +368,45 @@ issued = tokens.issue_token(
 The SDK sends it as `presence: {verified: true, uv: true, method, verified_at}` -- `verified`/`uv` are literal true by construction and the class cannot represent anything else; a raw Hash is rejected so the wire contract stays owned by the typed class. The hosted service validates freshness (10-minute window, 60 s future clock-skew slack) and stores the method provenance-marked `app:<method>` so app-attested facts stay distinct from ceremonies AgentAdmit witnessed itself. Introspection, the grant-event ledger, and the evidence API then carry `presence.verified: true` for the connection.
 
 Honesty ceiling: this is your app's attestation, recorded and provenance-marked. It is not witnessed by AgentAdmit and not independently verifiable. Only attest a ceremony that verified the user with UV (biometric or PIN user verification); a ceremony without UV carries no presence fact, so pass `nil` (the default). An out-of-contract method (`^[a-z0-9_]+$`, 1-60) raises `ArgumentError` at construction, before any request; Ruby `Time`/`DateTime` always carry an offset, so `verified_at` serializes RFC 3339 with an explicit offset by construction.
+
+## Per-Call Audit Telemetry
+
+Every verified call reports the exercised scope, endpoint, and method to your app's tamper-evident audit log on the hosted service. The introspection request body carries three optional fields alongside the token:
+
+- `scope_used` -- the single declared scope this call enforces (never a joined list)
+- `endpoint` -- the request path only; the query string is stripped before sending (queries can carry PII) and the path is truncated to 500 characters
+- `method` -- the HTTP method, uppercased, capped at 20 characters
+
+Each field is sent whenever it is known and OMITTED when it is not -- never null, never an empty string. When a field is omitted, the audit row honestly records "not reported".
+
+The Rack middleware always sends `endpoint` (from `PATH_INFO`) and `method`; declare the enforced scope at mount time to send `scope_used` too:
+
+```ruby
+# Scope resolved per request (env -> scope String or nil) ...
+use AgentAdmit::Middleware, scope_for: ->(env) { SCOPES[env["PATH_INFO"]] }
+# ... or one static scope for everything behind this middleware.
+use AgentAdmit::Middleware, scope_for: "read:orders"
+```
+
+`AgentAdmit::CallerConsent` reports its configured scope too and sets the hosted `consent_first` guard automatically, so denied caller classes receive no scope-state disclosure. Direct client calls pass the same optional keyword arguments:
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(
+  token,
+  scope_used: "read:orders",
+  endpoint: request.path,
+  method: request.request_method
+)
+```
+
+The local `ScopeEnforcement` checks (`require_scope!`, `require_scope_if_agent!`) are unchanged -- defense in depth on top of the hosted decision.
+
+### Active-error responses are denials
+
+An introspection response with `active: true` AND a string `error` field means the token itself is valid but the authorization service refused this call. The SDK treats every such response as a denial, never a pass-through -- the downstream app does not run:
+
+- `insufficient_scope` -> `AgentAdmit::InsufficientScopeError`; middlewares return 403 with the step-up shape (`error`, `required_scope`, `granted_scopes`)
+- `bound_exceeded` -> `AgentAdmit::BoundExceededError`; middlewares return 403 passing the hosted fields (`error_description`, `bound`, `renewal`) through verbatim
+- any other error string -> `AgentAdmit::ActiveDenialError`; middlewares return 403 with `{error: <code>, error_description: "Call refused by the authorization service."}` -- unknown codes fail closed
+
+All three inherit from `AgentAdmit::ActiveDenialError` and expose `#code`, `#data` (the parsed hosted response), and `#denial_body` (the ready-made 403 JSON body) for apps that call `verify` directly.

data/lib/agentadmit/caller_consent.rb

@@ -134,33 +134,33 @@ module AgentAdmit
       token = (env["HTTP_AUTHORIZATION"] || "").sub(/\Abearer /i, "")
 
       begin
-        result = @client.verify(token)
+        # Declare the exact exercised scope in the same hosted round trip.
+        # consent_first guarantees a denied caller class cannot learn scope
+        # state before this middleware returns its consent 403.
+        result = @client.verify(token,
+                                scope_used: @required_scope,
+                                endpoint: env["PATH_INFO"],
+                                method: env["REQUEST_METHOD"],
+                                consent_first: true)
+      rescue InsufficientScopeError
+        # Hosted consent-first ordering guarantees this refusal is reachable
+        # only after consent was granted.
+        return [403, { "Content-Type" => "application/json" },
+                [{ error: "insufficient_scope",
+                   message: "Call refused by the authorization service." }.to_json]]
+      rescue ActiveDenialError => e
+        # Token valid, call refused (bound_exceeded or an unknown error
+        # string on an active response). Fail closed: 403, app never runs.
+        return [403, { "Content-Type" => "application/json" },
+                [e.denial_body.to_json]]
       rescue InvalidTokenError => e
         return json_error(401, "invalid_token", e.message)
       rescue IntrospectionError => e
         return json_error(502, "introspection_failed", e.message)
       end
 
-      consent = result.consent
-      unless consent.is_a?(Hash) && [true, false].include?(consent["granted"])
-        owner = result.user_id
-        if !owner.is_a?(String) || owner.empty?
-          return json_error(503, "consent_unavailable",
-                            "Introspection carried no consent verdict and no resolvable data owner")
-        end
-
-        begin
-          consent = @client.check_consent(app_user_id: owner, caller_class: EXTERNAL_AGENT,
-                                          scope_group: @scope_group)
-        rescue StandardError
-          return json_error(503, "consent_unavailable", "Consent check failed")
-        end
-      end
-
-      unless consent.is_a?(Hash) && consent["granted"] == true
-        return json_error(403, "consent_not_granted",
-                          "The data owner has not enabled external agent access.")
-      end
+      status, consent = resolve_external_consent(result.consent, result.user_id)
+      return consent unless status == :granted
 
       if @required_scope && !(result.scopes || []).include?(@required_scope)
         return [403, { "Content-Type" => "application/json" },
@@ -181,6 +181,50 @@ module AgentAdmit
       @app.call(env)
     end
 
+    ##
+    # Resolve the external-agent consent verdict, fail-closed. An inline
+    # boolean verdict is authoritative; an absent or malformed one is
+    # resolved through the Consent Ledger (absence is never a grant), using
+    # the owner from the introspection payload.
+    #
+    # @return [Array] [:granted, verdict Hash] when the class is allowed,
+    #   otherwise [:denied | :unavailable, Rack response triple] ready to
+    #   return.
+    #
+    def resolve_external_consent(consent, owner)
+      unless consent.is_a?(Hash) && [true, false].include?(consent["granted"])
+        if !owner.is_a?(String) || owner.empty?
+          return [:unavailable,
+                  json_error(503, "consent_unavailable",
+                             "Introspection carried no consent verdict and no resolvable data owner")]
+        end
+
+        begin
+          consent = @client.check_consent(app_user_id: owner, caller_class: EXTERNAL_AGENT,
+                                          scope_group: @scope_group)
+        rescue StandardError
+          return [:unavailable, json_error(503, "consent_unavailable", "Consent check failed")]
+        end
+      end
+
+      unless consent.is_a?(Hash) && consent["granted"] == true
+        return [:denied,
+                json_error(403, "consent_not_granted",
+                           "The data owner has not enabled external agent access.")]
+      end
+
+      [:granted, consent]
+    end
+
+    ##
+    # A hosted insufficient_scope refusal (active: true, valid token). The
+    # class consent decision still comes first: a caller whose class the
+    # owner denied must not learn scope state, so the verdict is resolved
+    # from the hosted payload (or the ledger, fail-closed) and a denied or
+    # unresolvable class gets its consent response, never the step-up shape.
+    # Only a consent-granted caller sees the 403 step-up body.
+    #
+
     ##
     # Token-less caller class (in_app_ai, or human_session under gate_human),
     # gated on the Consent Ledger. Fail closed: an unreachable or erroring

data/lib/agentadmit/introspection_client.rb

@@ -71,13 +71,27 @@ module AgentAdmit
     # Automatically retries on HTTP 429 with exponential backoff + jitter.
     # Raises {RateLimitError} when retries are exhausted.
     #
+    # Per-call audit telemetry (all optional, all omitted from the request
+    # body when unknown -- never sent as null or empty string):
+    #
     # @param token [String] The full token including ag_at_ prefix
+    # @param scope_used [String, nil] the single scope this call enforces
+    #   (from the scope-enforcing integration point). Never a joined list;
+    #   omit for bare auth resolution / presence-only gates.
+    # @param endpoint [String, nil] inbound request path. Sent path-only:
+    #   the query string is stripped (queries can carry PII) and the path is
+    #   truncated to 500 characters.
+    # @param method [String, nil] inbound HTTP method; sent uppercased,
+    #   capped at 20 characters.
     # @return [IntrospectionResult]
     # @raise [InvalidTokenError] if validation fails
+    # @raise [ActiveDenialError] (incl. {InsufficientScopeError},
+    #   {BoundExceededError}) if the response is active but carries an error
+    #   string -- the service refused this call; always a denial
     # @raise [IntrospectionError] if the service is unreachable
     # @raise [RateLimitError] if rate-limited and retries exhausted
     #
-    def verify(token)
+    def verify(token, scope_used: nil, endpoint: nil, method: nil, consent_first: false)
       unless token.start_with?(@config.token_prefix_access)
         raise InvalidTokenError, "Not an AgentAdmit access token"
       end
@@ -90,7 +104,9 @@ module AgentAdmit
       http = build_http(uri)
 
       (0..max_retries).each do |attempt|
-        request = build_request(uri, token)
+        request = build_request(uri, token, scope_used: scope_used,
+                                endpoint: endpoint, method: method,
+                                consent_first: consent_first)
 
         begin
           response = http.request(request)
@@ -165,10 +181,13 @@ module AgentAdmit
           raise InvalidTokenError.new("Token is not active: #{reason}", code: reason)
         end
 
-        # insufficient_scope arrives with active: true (token valid,
-        # requested scope not granted).
-        if data["error"] == "insufficient_scope"
-          raise InsufficientScopeError, data["error_description"] || "Scope not granted"
+        # Active-error fail-closed: `active: true` with a string `error`
+        # means the token is valid but the authorization service refused
+        # THIS call (insufficient_scope, bound_exceeded, or anything the
+        # service may add later). Every such response is a DENIAL, never a
+        # pass-through -- unknown error strings included.
+        if data["error"].is_a?(String) && !data["error"].empty?
+          raise_active_denial!(data, scope_used)
         end
 
         # Validate that consumed fields have the expected types when present.
@@ -310,14 +329,86 @@ module AgentAdmit
       http
     end
 
-    def build_request(uri, token)
+    ##
+    # Map an active-response error string to its typed denial (always raises).
+    #
+    #  - insufficient_scope: token valid, enforced scope not granted. Carries
+    #    the step-up fields: required_scope from the hosted response when
+    #    present, else the scope this call enforced; granted_scopes from the
+    #    hosted response when present.
+    #  - bound_exceeded: the hosted bounded-capabilities layer refused the
+    #    call; hosted fields ride along verbatim on the error's data.
+    #  - anything else: unknown refusal -> generic typed denial. Fail closed.
+    #
+    def raise_active_denial!(data, scope_used)
+      case data["error"]
+      when "insufficient_scope"
+        required = data["required_scope"].is_a?(String) ? data["required_scope"] : scope_used
+        granted  = data["granted_scopes"]
+        granted  = data["scopes"] unless granted.is_a?(Array)
+        granted  = nil unless granted.is_a?(Array)
+        raise InsufficientScopeError.new(
+          data["error_description"] || "Scope not granted",
+          required_scope: required, granted_scopes: granted, data: data
+        )
+      when "bound_exceeded"
+        raise BoundExceededError.new(
+          data["error_description"] || "Call refused by the authorization service.",
+          data: data
+        )
+      else
+        raise ActiveDenialError.new(
+          "Call refused by the authorization service.",
+          code: data["error"], data: data
+        )
+      end
+    end
+
+    ##
+    # Build the introspection POST. Beyond the token, the body carries the
+    # per-call audit telemetry when known: scope_used (the single scope this
+    # call enforces), endpoint (path only -- query stripped, queries can
+    # carry PII -- truncated to 500 chars), method (uppercase, capped at
+    # 20). Unknown fields are OMITTED, never sent as null or empty string --
+    # the hosted audit row then honestly records "not reported".
+    #
+    def build_request(uri, token, scope_used: nil, endpoint: nil, method: nil,
+                      consent_first: false)
       req = Net::HTTP::Post.new(uri.path)
       req["Authorization"] = "Bearer #{@config.api_key}"
       req["Content-Type"]  = "application/json"
-      req.body = JSON.generate({ token: token })
+
+      body = { token: token }
+      scope = presence_of(scope_used)
+      body[:scope_used] = scope if scope
+      path = normalize_endpoint(endpoint)
+      body[:endpoint] = path if path
+      verb = presence_of(method)
+      body[:method] = verb.upcase[0, 20] if verb
+      body[:consent_first] = true if consent_first
+
+      req.body = JSON.generate(body)
       req
     end
 
+    # The value when it is a non-empty String, else nil (field omitted).
+    def presence_of(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    # Path only: strip everything from the first "?" (query strings can
+    # carry PII) and cap at 500 characters. nil when nothing usable remains
+    # so the field is omitted, never null.
+    def normalize_endpoint(endpoint)
+      path = presence_of(endpoint)
+      return nil unless path
+
+      path = path.split("?", 2).first
+      return nil if path.nil? || path.empty?
+
+      path[0, 500]
+    end
+
     ##
     # Parse a response header as Float, returning nil if absent or non-numeric.
     #

data/lib/agentadmit/middleware.rb

@@ -13,15 +13,34 @@ module AgentAdmit
   #   env['agentadmit.agent_label']   -- agent display name
   #   env['agentadmit.presence']      -- human-presence block (Hash) or nil
   #
+  # Every verify call carries per-call audit telemetry: the request path
+  # (PATH_INFO -- no query string) and the uppercase HTTP method, plus the
+  # scope the call enforces when the middleware is mounted with one:
+  #
+  #   # scope resolved per request (env -> scope String or nil) ...
+  #   use AgentAdmit::Middleware, scope_for: ->(env) { SCOPES[env["PATH_INFO"]] }
+  #   # ... or one static scope for everything behind this middleware
+  #   use AgentAdmit::Middleware, scope_for: "read:orders"
+  #
+  # When no scope is known the field is omitted (never null) and the hosted
+  # audit row records "not reported". The local ScopeEnforcement checks
+  # remain unchanged -- defense in depth.
+  #
+  # An introspection response with active: true AND an error string is a
+  # DENIAL: the token is valid but the authorization service refused this
+  # call (insufficient_scope, bound_exceeded, or an error code this SDK has
+  # never heard of). The middleware returns 403 and never calls the app.
+  #
   class Middleware
     # RFC 7235: the auth-scheme token is case-insensitive.
     # Match "bearer", "Bearer", "BEARER", etc. followed by the ag_at_ prefix.
     BEARER_AGENT_RE = /\Abearer ag_at_/i
 
-    def initialize(app)
+    def initialize(app, scope_for: nil)
       @app = app
       @client = IntrospectionClient.new
       @config = AgentAdmit.configuration || Config.new
+      @scope_for = scope_for
     end
 
     def call(env)
@@ -32,13 +51,21 @@ module AgentAdmit
         token = auth.sub(/\Abearer /i, "")
 
         begin
-          result = @client.verify(token)
+          result = @client.verify(token,
+                                  scope_used: resolve_scope(env),
+                                  endpoint: env["PATH_INFO"],
+                                  method: env["REQUEST_METHOD"])
           env["agentadmit.auth_type"] = "agent"
           env["agentadmit.user_id"] = result.user_id
           env["agentadmit.scopes"] = result.scopes
           env["agentadmit.connection_id"] = result.connection_id
           env["agentadmit.agent_label"] = result.agent_label
           env["agentadmit.presence"] = result.presence
+        rescue ActiveDenialError => e
+          # Token valid, call refused (active: true + error). Fail closed:
+          # 403 with the denial's contract shape; the app never runs.
+          return [403, { "Content-Type" => "application/json" },
+            [e.denial_body.to_json]]
         rescue InvalidTokenError => e
           return [401, { "Content-Type" => "application/json" },
             [{ error: "invalid_token", error_description: e.message }.to_json]]
@@ -50,5 +77,18 @@ module AgentAdmit
 
       @app.call(env)
     end
+
+    private
+
+    ##
+    # The scope this request enforces, when the app declared one at mount
+    # time. scope_for may be a Proc (env -> scope String or nil) or a
+    # static String; nil (the default) omits scope_used from the verify body.
+    #
+    def resolve_scope(env)
+      return @scope_for.call(env) if @scope_for.respond_to?(:call)
+
+      @scope_for
+    end
   end
 end

data/lib/agentadmit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.9.0"
+  VERSION = "1.10.1"
 end

data/lib/agentadmit.rb

@@ -20,7 +20,84 @@ module AgentAdmit
     end
   end
 
-  class InsufficientScopeError < Error; end
+  ##
+  # Raised when the hosted /verify returns `active: true` together with a
+  # string `error` field: the token itself is valid, but the authorization
+  # service refused THIS call. Always a denial, never a pass-through --
+  # middlewares map it to HTTP 403, and unknown error strings fail closed
+  # (forward compatible: an error code this SDK version has never heard of
+  # must never be treated as a pass).
+  #
+  # {#code} carries the machine-readable error string; {#data} carries the
+  # parsed hosted response so denial responses can pass hosted fields
+  # through; {#denial_body} is the ready-made 403 JSON body.
+  #
+  class ActiveDenialError < Error
+    # @return [String] machine-readable error code from the active response
+    attr_reader :code
+    # @return [Hash] the parsed hosted introspection response
+    attr_reader :data
+
+    def initialize(message = "Call refused by the authorization service.",
+                   code: "access_denied", data: {})
+      super(message)
+      @code = code
+      @data = data
+    end
+
+    # The HTTP 403 body for this denial. Unknown codes get the generic
+    # fail-closed shape; subclasses override with their contract shape.
+    # @return [Hash]
+    def denial_body
+      { "error" => code,
+        "error_description" => "Call refused by the authorization service." }
+    end
+  end
+
+  ##
+  # `active: true` + `error: "insufficient_scope"` -- token valid, the scope
+  # this call enforces not granted. {#denial_body} is the spec step-up shape
+  # (error, required_scope, granted_scopes).
+  #
+  class InsufficientScopeError < ActiveDenialError
+    # @return [String, nil] the scope the call enforced (hosted value when
+    #   present, else the scope_used this SDK sent)
+    attr_reader :required_scope
+    # @return [Array<String>, nil] granted scopes from the hosted response
+    attr_reader :granted_scopes
+
+    def initialize(message = "Scope not granted", required_scope: nil,
+                   granted_scopes: nil, data: {})
+      super(message, code: "insufficient_scope", data: data)
+      @required_scope = required_scope
+      @granted_scopes = granted_scopes
+    end
+
+    def denial_body
+      { "error" => "insufficient_scope",
+        "required_scope" => required_scope,
+        "granted_scopes" => granted_scopes || [] }
+    end
+  end
+
+  ##
+  # `active: true` + `error: "bound_exceeded"` -- the hosted bounded-
+  # capabilities layer refused the call. {#denial_body} passes the hosted
+  # fields (error_description, bound, renewal) through verbatim.
+  #
+  class BoundExceededError < ActiveDenialError
+    def initialize(message = "Call refused by the authorization service.", data: {})
+      super(message, code: "bound_exceeded", data: data)
+    end
+
+    def denial_body
+      body = { "error" => "bound_exceeded", "error_description" => message }
+      body["bound"]   = data["bound"]   if data.key?("bound")
+      body["renewal"] = data["renewal"] if data.key?("renewal")
+      body
+    end
+  end
+
   class IntrospectionError < Error; end
   class ConfigurationError < Error; end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.1
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json