agentadmit 1.8.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9903cf0e0365cc82696a35748e5736582e4d2e9aad33e9c956c62df61c4c5eea
-  data.tar.gz: e1cbbc38ef3ca551b003574383e759056f3c6f90c2224fc4cd8dc68af836c270
+  metadata.gz: ccda6bad890712e5c6060b2c33d02df1b1245ff48918a267cede579acf3f0d84
+  data.tar.gz: 5ef222b57006bcba2bd589c2b6276117abcfac031230263a8063ef56449cf355
 SHA512:
-  metadata.gz: c3089318cad6fd8c1914a3f087b9e9e2351ee0131b81d6bd288a9fa736868ce6c64937de4a248c0c3c4162c2d4b481e044ef2c642d917d368499e42dd6a72e93
-  data.tar.gz: 2f2d55a5ea98bc761ccabd6cce0e3e5ac417b0b5b659094c05ca74178abd77752e392c6b6104621ab750ba97aa1264f5b4d541e47c4a243e20b037b1417b69ab
+  metadata.gz: a703d18e7a9a55ed4a34b07d2ed295ddfbc49fabdba0caef6b49ef0a57cb670097b78ef5a53849035e22cc3a29709977836df8b8bdd4f660fc09bb20adaac84e
+  data.tar.gz: 06a8b43f3a18b696df4ddccb6abb0130c62addff9d4ab948b51ea6ea1d2b0e2bf2cdb11b5cd1da90734fc94d9b6f7e3512f9fae536563418d4d8a361fc058a8b

data/README.md

@@ -349,3 +349,64 @@ result.user_intent # => "Book my flights to the Austin offsite in October" or ni
 ```
 
 `user_intent` is nullable -- connections issued without one (or by servers that predate the field) read as `nil`. Months later, a review screen can answer "is this still appropriate?" with the user's own stated boundary, not just the app's. Like purpose, it is a review-time record and never an enforcement input; authorization decisions ride scopes, connection status, and consent.
+
+## App-Attested Presence
+
+If your app gates token minting behind its own embedded passkey/WebAuthn ceremony, AgentAdmit never witnesses that ceremony (it is origin-bound), so by default the hosted service reports `presence.verified: false` for those connections. Attest the ceremony fact at issuance to close that gap -- AFTER verifying and consuming your own fresh, purpose-bound attestation:
+
+```ruby
+issued = tokens.issue_token(
+  user_id: "user_42",
+  scopes: ["read:orders"],
+  presence: AgentAdmit::AppAttestedPresence.new(
+    method: "my_webauthn",             # lowercase alphanumeric/underscore
+    verified_at: attestation.created_at # Time or DateTime
+  )
+)
+```
+
+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` never sends `scope_used` (its consent gate precedes any scope disclosure; the scope check stays local, after consent) but still reports endpoint and method. 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/app_attested_presence.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "time"
+
+module AgentAdmit
+  ##
+  # App-attested presence: a ceremony fact your app attests at token issuance.
+  #
+  # Pass an instance to TokensClient#issue_token AFTER verifying and consuming
+  # your app's own fresh, purpose-bound WebAuthn/passkey attestation for the
+  # mint. The SDK forwards it to the hosted mint as
+  # presence {verified: true, uv: true, method, verified_at}; the hosted
+  # service stores it method-prefixed "app:<method>" — the provenance marker
+  # that keeps app-attested facts distinct from hosted-witnessed ceremonies.
+  #
+  # Honesty ceiling: this is YOUR attestation, recorded and provenance-marked.
+  # It is not witnessed by AgentAdmit and not independently verifiable. Only
+  # construct one for a ceremony that verified the user with UV (biometric or
+  # PIN user verification); verified/uv serialize as literal true and cannot
+  # represent anything else — a ceremony without UV carries no presence fact,
+  # so simply pass nil.
+  #
+  # verified_at must be recent: the hosted service enforces a 10-minute
+  # freshness window with 60 seconds of future clock-skew slack. Ruby Time and
+  # DateTime always carry an offset, so #iso8601 serializes RFC 3339 with an
+  # explicit offset by construction (the hosted contract; offset-less
+  # timestamps are rejected with 400).
+  #
+  class AppAttestedPresence
+    METHOD_PATTERN = /\A[a-z0-9_]+\z/
+    METHOD_MAX_LENGTH = 60
+
+    # NOTE: a +method+ reader shadows Object#method on instances — the same
+    # trade stdlib's Net::HTTPGenericRequest makes; the name matches the wire
+    # field.
+    attr_reader :method, :verified_at
+
+    ##
+    # @param method [String] your ceremony mechanism, 1-60 lowercase
+    #   alphanumeric/underscore characters (e.g. "my_webauthn")
+    # @param verified_at [Time, DateTime] when the ceremony completed
+    # @raise [ArgumentError] when method is out of contract or verified_at is
+    #   not a timestamp — validated at construction, before any request,
+    #   where the fix is obvious
+    #
+    def initialize(method:, verified_at:)
+      unless method.is_a?(String) && !method.empty? &&
+             method.length <= METHOD_MAX_LENGTH && METHOD_PATTERN.match?(method)
+        raise ArgumentError,
+              "method must be 1-#{METHOD_MAX_LENGTH} lowercase alphanumeric/underscore " \
+              "characters (e.g. 'my_webauthn')"
+      end
+      unless verified_at.respond_to?(:iso8601)
+        raise ArgumentError,
+              "verified_at must be a Time or DateTime (the ceremony that authorized " \
+              "this mint just happened)"
+      end
+
+      @method = method
+      @verified_at = verified_at
+    end
+
+    ##
+    # The exact JSON object forwarded to the hosted mint.
+    #
+    # @return [Hash]
+    #
+    def to_wire
+      {
+        "verified" => true,
+        "uv" => true,
+        "method" => @method,
+        "verified_at" => @verified_at.iso8601
+      }
+    end
+  end
+end

data/lib/agentadmit/caller_consent.rb

@@ -134,33 +134,37 @@ module AgentAdmit
       token = (env["HTTP_AUTHORIZATION"] || "").sub(/\Abearer /i, "")
 
       begin
-        result = @client.verify(token)
+        # The verify body carries endpoint/method audit telemetry only.
+        # scope_used is deliberately NOT sent from this middleware: the
+        # hosted refusal body carries no consent verdict and no user_id, so
+        # a hosted scope refusal here could not be consent-resolved -- and
+        # consent must precede any scope disclosure (Patent FIG. 3). The
+        # scope check stays local, after the consent gate, exactly as the
+        # other AgentAdmit SDKs do.
+        result = @client.verify(token,
+                                endpoint: env["PATH_INFO"],
+                                method: env["REQUEST_METHOD"])
+      rescue InsufficientScopeError
+        # Unreachable when this middleware performs the verify (scope_used
+        # is never sent, so the hosted service cannot refuse on scope).
+        # Kept as a fail-closed guard that reveals no scope state to a
+        # caller class whose consent was never evaluated.
+        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 +185,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)
       unless token.start_with?(@config.token_prefix_access)
         raise InvalidTokenError, "Not an AgentAdmit access token"
       end
@@ -90,7 +104,8 @@ 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)
 
         begin
           response = http.request(request)
@@ -165,10 +180,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 +328,84 @@ 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)
       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
+
+      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/tokens_client.rb

@@ -54,14 +54,21 @@ module AgentAdmit
     #   user's typed words would be data loss. Empty/whitespace-only strings
     #   normalize to nil and are omitted. Like purpose, it is a review-time
     #   record, never an enforcement input.
+    # @param presence [AppAttestedPresence, nil] app-attested ceremony fact:
+    #   set it AFTER verifying and consuming your app's own fresh,
+    #   purpose-bound WebAuthn/passkey attestation for this mint. Forwarded
+    #   as presence {verified: true, uv: true, method, verified_at} and
+    #   stored provenance-marked "app:<method>"; omitted when nil (omitting
+    #   the field is the only way to say "no ceremony").
     # @return [Hash] the issue response — "token" is the self-describing
     #   ag_ct_… connection token to hand to the user's agent
-    # @raise [ArgumentError] if purpose exceeds 300 characters, or if
-    #   user_intent is a non-String (other than nil) or exceeds 300 characters
+    # @raise [ArgumentError] if purpose exceeds 300 characters, if
+    #   user_intent is a non-String (other than nil) or exceeds 300
+    #   characters, or if presence is neither nil nor an AppAttestedPresence
     # @raise [IntrospectionError] if issuance fails
     #
     def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET, purpose: nil,
-                    user_intent: nil)
+                    user_intent: nil, presence: nil)
       if purpose && purpose.length > PURPOSE_MAX_LENGTH
         raise ArgumentError, "purpose must be at most #{PURPOSE_MAX_LENGTH} characters"
       end
@@ -77,10 +84,18 @@ module AgentAdmit
       end
       user_intent = nil if user_intent && user_intent.strip.empty?
 
+      # Presence is typed-only: a raw Hash is rejected so the wire contract
+      # (literal-true verified/uv, offset-carrying verified_at) stays owned
+      # by AppAttestedPresence, never hand-rolled at call sites.
+      unless presence.nil? || presence.is_a?(AppAttestedPresence)
+        raise ArgumentError, "presence must be an AgentAdmit::AppAttestedPresence or nil"
+      end
+
       body = { "user_id" => user_id, "scopes" => scopes }
       body["role"] = role if role
       body["purpose"] = purpose if purpose
       body["user_intent"] = user_intent if user_intent
+      body["presence"] = presence.to_wire if presence
       # Tri-state: the UNSET sentinel omits the key entirely; nil survives
       # JSON.generate as explicit JSON null (no compact, no nil-guard).
       body["duration_seconds"] = duration_seconds unless duration_seconds.equal?(UNSET)

data/lib/agentadmit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.8.0"
+  VERSION = "1.10.0"
 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
 
@@ -88,6 +165,7 @@ end
 
 require_relative "agentadmit/config"
 require_relative "agentadmit/introspection_client"
+require_relative "agentadmit/app_attested_presence"
 require_relative "agentadmit/tokens_client"
 require_relative "agentadmit/alerts_client"
 require_relative "agentadmit/webhook"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -35,6 +35,7 @@ files:
 - README.md
 - lib/agentadmit.rb
 - lib/agentadmit/alerts_client.rb
+- lib/agentadmit/app_attested_presence.rb
 - lib/agentadmit/caller_consent.rb
 - lib/agentadmit/config.rb
 - lib/agentadmit/introspection_client.rb