agentadmit 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 501b7f18f13450e559d3a58aa7060fdee56eb167b33e60245a7b734d900cf0b8
-  data.tar.gz: dedcb0707371dfec628f2e0f8dfb0a7ee98d02260626a4601d99de30f22bb28e
+  metadata.gz: 3d3b45175d51202f94a44cfda45acd2eedbd6e96453686633e2c23fe1e9e4b07
+  data.tar.gz: 8e6e17f6848db25e36996afcb1e16ed45ec0ab591647cdc9bbd56f51b1b1957d
 SHA512:
-  metadata.gz: e23e66f76f7de6817786c206103e26eb1ebd3c3e6b36888f8d0028f2c092a8c1dd034fcdd4537554af2ea04f3f86ea31428967db5d41ebe93e276bcdb984ab08
-  data.tar.gz: 9f2a13f32307706d2ae85c7f04b6cb729a0975645264deb560108d3fa5ab892e0153c0e86467e9b97c01f72dd362581dbed9b905db420fe86c7df7e072087ce6
+  metadata.gz: e77aed424389ce8a3c15445505cf32cadad2f04a004d4eb003b06c07891556c1968dda9c27506045ea7762c054f31b26c5c7271b79c96fc696423edee7655a6f
+  data.tar.gz: 4526e4389bc7dad6a0799d0633082f9c885afff37c4aaa80be55065856d82a507bf12d20270e27cb636a057342995e880aeaa5734edfbfe8bd67e2110cb61223

data/README.md

@@ -177,6 +177,19 @@ fail-closed `ActiveDenialError` instances with no link. On an accepted retry,
 expose the consumed ceremony so your own transaction step-up can avoid asking
 the human twice.
 
+**The user can decline.** If the user taps Decline on the hosted page, the
+hosted service answers the agent's retry with `confirmation_declined` and
+holds that answer until `declined["hold_until"]`; no new ceremony is staged
+and the user is not notified again. Middlewares return 403 with the strictly
+typed `declined` block (`action_session_id`, `declined_at`, `hold_until`,
+`scope`, plus nullable `method`, `endpoint`, `request_digest`, `summary`) and
+`renewal`; custom gates receive `AgentAdmit::ConfirmationDeclinedError` (an
+`ActiveDenialError`) with `.declined` and `.attestation_status`. Agents should
+relay the decline to the user and not retry unless the user asks; only the
+user can lift a decline, and after the hold ends a retry stages a fresh
+confirmation. A malformed `declined` block degrades to a generic 403 with no
+block.
+
 ## Rate Limiting
 
 The AgentAdmit introspection endpoint enforces rate limits. The Ruby SDK handles HTTP 429 responses **automatically** with exponential backoff and jitter -- no changes needed in your middleware code.
@@ -436,6 +449,77 @@ result = AgentAdmit::IntrospectionClient.new.verify(
 
 The local `ScopeEnforcement` checks (`require_scope!`, `require_scope_if_agent!`) are unchanged -- defense in depth on top of the hosted decision.
 
+### Outcome reporting
+
+Successful verify responses may include `result.audit_row_id`, the hosted
+audit row id for that call. After your handler runs, you can append what your
+app observed:
+
+```ruby
+client = AgentAdmit::IntrospectionClient.new
+result = client.verify(token, scope_used: "write:payments",
+                       endpoint: request.path, method: request.request_method)
+
+begin
+  # run the app action
+  client.report_outcome(result.audit_row_id,
+                        outcome: "executed",
+                        status_class: "2xx") if result.audit_row_id
+rescue
+  client.report_outcome(result.audit_row_id,
+                        outcome: "failed",
+                        status_class: "5xx") if result.audit_row_id
+  raise
+end
+```
+
+`outcome` must be `"executed"`, `"failed"`, or `"unknown"`. `unknown` is
+only for an explicit "we cannot truthfully classify this" case; it is never
+chosen automatically. `status_class` may be `"1xx"` through `"5xx"` or `nil`.
+Outcome rows report what the app observed after verification; they are not
+independent proof of execution.
+
+Rack middleware can do the common status mapping for you:
+
+```ruby
+use AgentAdmit::Middleware,
+    scope_for: "write:payments",
+    action_summary: ->(env) { "Pay Alex $50" },
+    report_outcome: true
+```
+
+With `report_outcome: true`, the middleware reports only after the downstream
+Rack app returns a response triple and the status has an observable class.
+Statuses below 400 report `"executed"`; statuses 400 and above report
+`"failed"`. If the app raises, aborts before returning a triple, returns no
+observable status, or verify did not include `audit_row_id`, the middleware
+does not guess. Reporting errors are logged and never replace the app's
+response.
+
+For downstream code, the Rack env includes `env["agentadmit.audit_row_id"]`
+when the hosted service returned one.
+
+### Replay receipts
+
+When an agent retries with an already-consumed confirm-each-time attestation,
+verify may return `result.consumed_receipt`. It is a diagnostic receipt for
+the earlier consumption event:
+
+```ruby
+result.consumed_receipt
+# => {
+#      "consumed_at" => "2026-09-30T02:54:07.000Z",
+#      "connection_id" => "conn_123",
+#      "chain_seq" => nil,
+#      "row_hash" => nil
+#    }
+```
+
+This is not a fresh authorization and must not be treated as permission to
+run the action. It exists so agents and apps can explain an
+`already_consumed` replay without staging another confirmation. Rack exposes
+the typed block at `env["agentadmit.consumed_receipt"]` when present.
+
 ### 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:
@@ -443,6 +527,7 @@ An introspection response with `active: true` AND a string `error` field means t
 - `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
 - `confirmation_required` -> `AgentAdmit::ConfirmationRequiredError`; middlewares return 403 with the strictly typed `confirmation` block (`action_session_id`, `action_session_url`, `expires_at`, `scope`, ...) plus `attestation_status`/`attestation_description`/`renewal` when the hosted service sent them, so the agent can relay the confirmation link to the human (see [Confirm Each Time](#confirm-each-time-exercise-time-human-confirmation)); a malformed `confirmation` block degrades to the generic `ActiveDenialError` shape with no link
+- `confirmation_declined` -> `AgentAdmit::ConfirmationDeclinedError`; middlewares return 403 with the strictly typed `declined` block (`action_session_id`, `declined_at`, `hold_until`, `scope`, ...) plus `attestation_status`/`attestation_description`/`renewal` when sent, so the agent can relay the user's decline instead of nagging with a link; a malformed `declined` block degrades to the generic shape with no block
 - 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 four 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/introspection_client.rb

@@ -27,11 +27,14 @@ module AgentAdmit
     ATTESTATION_MAX = 120
     DIGEST_MAX      = 128
     SUMMARY_MAX     = 200
+    OUTCOMES        = %w[executed failed unknown].freeze
+    STATUS_CLASSES  = %w[1xx 2xx 3xx 4xx 5xx].freeze
 
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
                                      :sub, :role, :app_id, :jti, :exp, :consent,
                                      :presence, :purpose, :user_intent,
-                                     :action_confirmation, keyword_init: true) do
+                                     :action_confirmation, :audit_row_id,
+                                     :consumed_receipt, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -83,9 +86,30 @@ module AgentAdmit
       def action_confirmed?
         action_confirmation.is_a?(Hash) && action_confirmation["consumed"] == true
       end
+
+      # `audit_row_id` (String or nil) identifies the hosted audit row for
+      # this successful verify call. Use it with #report_outcome after the
+      # application observes whether its handler executed or failed.
+
+      # `consumed_receipt` (Hash or nil) is a replay diagnostic for an
+      # already-consumed confirm-each-time attestation. It is not a fresh
+      # authorization and must not be treated as permission to run.
     end
 
     class << self
+      def status_class_for(status)
+        code = Integer(status) rescue nil
+        return nil unless code && (100..599).cover?(code)
+
+        "#{code / 100}xx"
+      end
+
+      def outcome_for_status(status)
+        status_class_for(status) ? (Integer(status) < 400 ? "executed" : "failed") : nil
+      rescue ArgumentError, TypeError
+        nil
+      end
+
       ##
       # `sha256:<hex>` over the RAW request body bytes, so a confirmation
       # covers the exact payload and not merely the route. nil for an empty
@@ -125,6 +149,49 @@ module AgentAdmit
           "summary"            => nullable.call(raw["summary"]) }
       end
 
+      ##
+      # A strictly-typed copy of the wire `declined` block (SDK 1.12.0), or
+      # nil when it is malformed. action_session_id, declined_at, hold_until
+      # and scope must be Strings; method, endpoint, request_digest and
+      # summary are nullable Strings (anything else reads as nil). Nothing
+      # outside the contract is copied through.
+      #
+      # @param raw [Object] the `declined` value from the hosted response
+      # @return [Hash, nil]
+      #
+      def parse_action_decline(raw)
+        return nil unless raw.is_a?(Hash)
+        return nil unless %w[action_session_id declined_at hold_until scope]
+                          .all? { |key| raw[key].is_a?(String) }
+
+        nullable = ->(value) { value.is_a?(String) ? value : nil }
+        { "action_session_id" => raw["action_session_id"],
+          "declined_at"       => raw["declined_at"],
+          "hold_until"        => raw["hold_until"],
+          "scope"             => raw["scope"],
+          "method"            => nullable.call(raw["method"]),
+          "endpoint"          => nullable.call(raw["endpoint"]),
+          "request_digest"    => nullable.call(raw["request_digest"]),
+          "summary"           => nullable.call(raw["summary"]) }
+      end
+
+      ##
+      # A strictly-typed replay diagnostic for an already-consumed action
+      # attestation, or nil when the block is absent/malformed. This is a
+      # receipt for an earlier consumption event, not authorization for this
+      # call.
+      #
+      def parse_consumed_receipt(raw)
+        return nil unless raw.is_a?(Hash)
+        return nil unless raw["consumed_at"].is_a?(String)
+        return nil unless raw["connection_id"].is_a?(String)
+
+        { "consumed_at"   => raw["consumed_at"],
+          "connection_id" => raw["connection_id"],
+          "chain_seq"     => raw["chain_seq"].is_a?(Integer) ? raw["chain_seq"] : nil,
+          "row_hash"      => raw["row_hash"].is_a?(String) ? raw["row_hash"] : nil }
+      end
+
       ##
       # The agent's X-AgentAdmit-Action-Attestation header from a Rack env:
       # first value only, trimmed, capped at 120 characters. nil when absent
@@ -337,6 +404,10 @@ module AgentAdmit
               "consumed" => true }
           end
 
+        audit_row_id = data["audit_row_id"]
+        audit_row_id = nil unless audit_row_id.is_a?(String)
+        consumed_receipt = self.class.parse_consumed_receipt(data["consumed_receipt"])
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -351,7 +422,9 @@ module AgentAdmit
           presence:     presence,
           purpose:      purpose,
           user_intent:  user_intent,
-          action_confirmation: action_confirmation
+          action_confirmation: action_confirmation,
+          audit_row_id: audit_row_id,
+          consumed_receipt: consumed_receipt
         )
       end
 
@@ -359,6 +432,60 @@ module AgentAdmit
       raise IntrospectionError, "Unexpected exit from retry loop"
     end
 
+    ##
+    # Report what the application observed after a successful verify call.
+    #
+    # This appends an outcome row to the hosted tamper-evident audit chain.
+    # It reports the app's observed result; it is not independent proof of
+    # execution. Use outcome: "unknown" only when you explicitly cannot
+    # classify the result.
+    #
+    # @param audit_row_id [String] result.audit_row_id from #verify
+    # @param outcome [String] "executed" | "failed" | "unknown"
+    # @param status_class [String, nil] "1xx".."5xx" or nil
+    # @return [Hash] parsed hosted outcome response
+    # @raise [ArgumentError] invalid arguments
+    # @raise [IntrospectionError] hosted service unreachable or rejected the report
+    #
+    def report_outcome(audit_row_id, outcome:, status_class: nil)
+      unless audit_row_id.is_a?(String) && !audit_row_id.empty?
+        raise ArgumentError, "audit_row_id is required"
+      end
+      unless OUTCOMES.include?(outcome)
+        raise ArgumentError, "outcome must be executed, failed, or unknown"
+      end
+      unless status_class.nil? || STATUS_CLASSES.include?(status_class)
+        raise ArgumentError, "status_class must be 1xx, 2xx, 3xx, 4xx, 5xx, or nil"
+      end
+
+      origin = @config.api_url.sub(%r{/\z}, "")
+      uri = URI.parse("#{origin}/api/v1/audit/#{audit_row_id}/outcome")
+      http = build_http(uri)
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Authorization"] = "Bearer #{@config.api_key}"
+      request["Content-Type"]  = "application/json"
+      request.body = JSON.generate(outcome: outcome, status_class: status_class)
+
+      response = begin
+        http.request(request)
+      rescue StandardError => e
+        raise IntrospectionError, "Outcome report failed: #{e.message}"
+      end
+
+      unless (200..299).cover?(response.code.to_i)
+        data = JSON.parse(response.body) rescue {}
+        raise IntrospectionError,
+              data["error_description"] || data["error"] || "Outcome report returned #{response.code}"
+      end
+
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise IntrospectionError, "Outcome report response is not valid JSON"
+      end
+    end
+
     CALLER_CLASSES = %w[human_session in_app_ai external_agent].freeze
 
     ##
@@ -462,6 +589,10 @@ module AgentAdmit
     #    typed, so the agent can hand the link to the human. A malformed
     #    ceremony block degrades to the generic denial -- fail closed rather
     #    than relay an unusable confirmation.
+    #  - confirmation_declined: the user declined this exact action on the
+    #    hosted page; the hold rides along, strictly typed, so the agent can
+    #    relay the decline to the user. A malformed block degrades to the
+    #    generic denial.
     #  - anything else: unknown refusal -> generic typed denial. Fail closed.
     #
     def raise_active_denial!(data, scope_used)
@@ -499,6 +630,28 @@ module AgentAdmit
           "Call refused by the authorization service.",
           code: "confirmation_required", data: data
         )
+      when "confirmation_declined"
+        # SDK 1.12.0: the user declined exactly this action on the hosted
+        # page and the hold still runs. Relay the decline so the agent can
+        # tell the user instead of nagging with a link.
+        declined = self.class.parse_action_decline(data["declined"])
+        if declined
+          description = data["error_description"]
+          description = ConfirmationDeclinedError::DESCRIPTION unless
+            description.is_a?(String) && !description.empty?
+          status = data["attestation_status"]
+          raise ConfirmationDeclinedError.new(
+            description,
+            declined: declined,
+            attestation_status: status.is_a?(String) ? status : nil,
+            data: data
+          )
+        end
+        # Malformed decline: generic denial, fail closed, no block.
+        raise ActiveDenialError.new(
+          "Call refused by the authorization service.",
+          code: "confirmation_declined", data: data
+        )
       else
         raise ActiveDenialError.new(
           "Call refused by the authorization service.",

data/lib/agentadmit/middleware.rb

@@ -12,6 +12,10 @@ module AgentAdmit
   #   env['agentadmit.connection_id'] -- connection identifier
   #   env['agentadmit.agent_label']   -- agent display name
   #   env['agentadmit.presence']      -- human-presence block (Hash) or nil
+  #   env['agentadmit.audit_row_id']  -- hosted audit row id for this verify
+  #   env['agentadmit.consumed_receipt']
+  #                                   -- replay diagnostic for an already-
+  #                                      consumed confirmation, or nil
   #   env['agentadmit.action_confirmation']
   #                                   -- {"action_session_id" =>, "consumed" => true}
   #                                      when a confirm-each-time confirmation
@@ -66,16 +70,25 @@ module AgentAdmit
     #   request-body digest for this middleware. AgentAdmit does not verify
     #   the summary against the request; it proves what the human was shown.
     #
-    def initialize(app, scope_for: nil, action_summary: nil, &action_summary_block)
+    # @param report_outcome [Boolean] when true, reports the downstream
+    #   Rack response status class to AgentAdmit after the app returns a
+    #   response triple. Reporting is skipped when the app raises, returns no
+    #   observable Rack triple, or has no audit_row_id. Reporting failures are
+    #   logged and never replace the app's response.
+    #
+    def initialize(app, scope_for: nil, action_summary: nil, report_outcome: false,
+                   &action_summary_block)
       @app = app
       @client = IntrospectionClient.new
       @config = AgentAdmit.configuration || Config.new
       @scope_for = scope_for
       @action_summary = action_summary || action_summary_block
+      @report_outcome = report_outcome
     end
 
     def call(env)
       auth = env["HTTP_AUTHORIZATION"] || ""
+      result = nil
 
       if BEARER_AGENT_RE.match?(auth)
         # Strip the scheme prefix (case-insensitively) to get the bare token.
@@ -96,6 +109,8 @@ module AgentAdmit
           env["agentadmit.connection_id"] = result.connection_id
           env["agentadmit.agent_label"] = result.agent_label
           env["agentadmit.presence"] = result.presence
+          env["agentadmit.audit_row_id"] = result.audit_row_id
+          env["agentadmit.consumed_receipt"] = result.consumed_receipt if result.consumed_receipt
           # Only set when the hosted service actually SPENT a confirmation on
           # this call; the key stays absent otherwise, so `env.key?` is a
           # truthful test.
@@ -116,7 +131,9 @@ module AgentAdmit
         end
       end
 
-      @app.call(env)
+      response = @app.call(env)
+      report_outcome_after_response(result, response) if @report_outcome && result
+      response
     end
 
     private
@@ -168,5 +185,20 @@ module AgentAdmit
     rescue StandardError
       nil
     end
+
+    def report_outcome_after_response(result, response)
+      return unless result.audit_row_id
+      return unless response.is_a?(Array) && response.length >= 3
+
+      status_class = IntrospectionClient.status_class_for(response[0])
+      outcome = IntrospectionClient.outcome_for_status(response[0])
+      return unless status_class && outcome
+
+      @client.report_outcome(result.audit_row_id,
+                             outcome: outcome,
+                             status_class: status_class)
+    rescue StandardError => e
+      warn "[AgentAdmit] Outcome report failed: #{e.message}"
+    end
   end
 end

data/lib/agentadmit/version.rb

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

data/lib/agentadmit.rb

@@ -154,6 +154,58 @@ module AgentAdmit
     end
   end
 
+  ##
+  # `active: true` + `error: "confirmation_declined"` (SDK 1.12.0,
+  # confirm-each-time) -- the user declined exactly this action on the hosted
+  # confirmation page, and the hosted service holds that answer until
+  # `declined["hold_until"]`. No new ceremony is staged and the user is not
+  # notified again while the hold runs. {#declined} is the strictly-typed
+  # block naming the declined session, when, how long, and the exact action.
+  #
+  # Agents should relay the decline to the user and not retry unless the user
+  # asks; only the user can lift a decline. After the hold ends, a retry
+  # stages a fresh confirmation.
+  #
+  # {#attestation_status} explains why a presented attestation was NOT
+  # accepted, when one was presented (e.g. declined).
+  #
+  # A malformed declined block never reaches this class: the client falls
+  # back to a generic {ActiveDenialError} (fail closed, 403, no declined
+  # block).
+  #
+  class ConfirmationDeclinedError < ActiveDenialError
+    # The canonical agent-facing description. The hosted `error_description`
+    # wins when the service sends one.
+    DESCRIPTION = "The user declined this action on the hosted confirmation page. " \
+                  "Do not retry it unless the user asks you to."
+
+    # @return [Hash] the strictly-typed decline: action_session_id,
+    #   declined_at, hold_until, scope (Strings), and method, endpoint,
+    #   request_digest, summary (String or nil).
+    attr_reader :declined
+    # @return [String, nil] why a presented attestation was not accepted.
+    attr_reader :attestation_status
+
+    def initialize(message = DESCRIPTION, declined:, attestation_status: nil, data: {})
+      super(message, code: "confirmation_declined", data: data)
+      @declined = declined
+      @attestation_status = attestation_status
+    end
+
+    # The 403 body: the refusal, the human-readable description, the decline,
+    # and the hosted attestation diagnostics when present. Nothing else from
+    # the wire -- a refusal must not leak identity or scope state.
+    def denial_body
+      body = { "error" => "confirmation_declined",
+               "error_description" => message,
+               "declined" => declined }
+      %w[attestation_status attestation_description renewal].each do |field|
+        body[field] = data[field] if data[field].is_a?(String)
+      end
+      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.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json