agentadmit 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 501b7f18f13450e559d3a58aa7060fdee56eb167b33e60245a7b734d900cf0b8
-  data.tar.gz: dedcb0707371dfec628f2e0f8dfb0a7ee98d02260626a4601d99de30f22bb28e
+  metadata.gz: 35cfc75d6a091ef7f5940c488c472efad1c6d48a68c670e6c5e1522dbe9abb06
+  data.tar.gz: 0a9c2ecbc1fcdab6255e709519625cc1dbc9944d36d2b9725d5069a44544b222
 SHA512:
-  metadata.gz: e23e66f76f7de6817786c206103e26eb1ebd3c3e6b36888f8d0028f2c092a8c1dd034fcdd4537554af2ea04f3f86ea31428967db5d41ebe93e276bcdb984ab08
-  data.tar.gz: 9f2a13f32307706d2ae85c7f04b6cb729a0975645264deb560108d3fa5ab892e0153c0e86467e9b97c01f72dd362581dbed9b905db420fe86c7df7e072087ce6
+  metadata.gz: 39bb513f8747187ffeb5d7bb73f4557c47a9da0a95f1bd8b56130f95b38406081befb47570f425afbdfbc1ca322069459c5ebf3e4fcb1f4c164320242c306882
+  data.tar.gz: 35577380cb5d5e783fe05e68c67c291238de414dd9b8fb99cb4d9ea8f75a5befed74c501ccd50e1a2eade6ffe3dc3d009d712ef5f44f1b1ba41e7928d8c20a99

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.
@@ -443,6 +456,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

@@ -125,6 +125,32 @@ 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
+
       ##
       # The agent's X-AgentAdmit-Action-Attestation header from a Rack env:
       # first value only, trimmed, capped at 120 characters. nil when absent
@@ -462,6 +488,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 +529,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.11.0"
+  VERSION = "1.12.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.12.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json