agentadmit 1.10.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 305d2a2680095a277efd613bbc48dc1c0e948109f05ce01aa995dbff99c172bc
-  data.tar.gz: 559cae430ea15ea9c66fb7e758efdab50fa652625d67f31bf7dab06d4606842d
+  metadata.gz: 35cfc75d6a091ef7f5940c488c472efad1c6d48a68c670e6c5e1522dbe9abb06
+  data.tar.gz: 0a9c2ecbc1fcdab6255e709519625cc1dbc9944d36d2b9725d5069a44544b222
 SHA512:
-  metadata.gz: 145b55beeabfec1d0860f8d2bdf772b28e2a4a8ca0926c814aac49c3f516bee31f1a66f4dd26c894803452a178bfd296083ec89143185e4c3925aa8d4ae7ac07
-  data.tar.gz: f1e2e43b3ea29c1f59a67d2b8791050d8058cac7210edac2cab8b9ef5f6915b35e91479d30ea3cd44709b1ccaaab16c855dc38851f8aab0ce567e1a693b7914f
+  metadata.gz: 39bb513f8747187ffeb5d7bb73f4557c47a9da0a95f1bd8b56130f95b38406081befb47570f425afbdfbc1ca322069459c5ebf3e4fcb1f4c164320242c306882
+  data.tar.gz: 35577380cb5d5e783fe05e68c67c291238de414dd9b8fb99cb4d9ea8f75a5befed74c501ccd50e1a2eade6ffe3dc3d009d712ef5f44f1b1ba41e7928d8c20a99

data/README.md

@@ -5,6 +5,8 @@ User-mediated AI agent authorization. Plug-and-play for any Rails app.
 > **Get started:** Sign up at [agentadmit.com](https://agentadmit.com) -- Get your test keys -- Install the SDK -- Build.
 > Test keys are available immediately after signup. Live keys become available when you subscribe an app.
 
+> **Where the consent step runs (live keys).** The agent grant is approved on the AgentAdmit **hosted consent page**, opened on your app's behalf: your backend creates a consent session (`POST /api/v1/apps/{app_id}/consent-sessions`) with your live key and sends the signed-in user to the returned `session_url`. Scope selection, duration, intent, existing-grant review, the passkey ceremony, and the one-time token all happen there. **Direct token issuance (`POST /api/v1/apps/{app_id}/token`, and this SDK's issue-token helpers and any SDK-mounted `generate-token` route) is a sandbox facility for `aa_test_` keys only; a live key receives `403 hosted_consent_required`.** Verification (`/verify`) is unchanged and is the core of this SDK. Full walkthrough: [App Owner Guide, Step 4](https://agentadmit.com/docs/app-owner-guide).
+
 ## Quick Start
 
 ```ruby
@@ -142,6 +144,52 @@ end
 
 `require_presence!` fails closed: agents whose connection was minted without a completed ceremony get a 403 `presence_required`, and so do connections from servers that predate the feature. `presence_verified?` returns true only on an explicit boolean `verified: true`; absent or malformed presence data reads as not verified.
 
+## Confirm Each Time (Exercise-Time Human Confirmation)
+
+Some actions should never run on a standing grant alone: moving money,
+sending or publishing on the user's behalf, deleting data, or touching
+production. Mark those scopes `confirm_each_time: true` when you register
+them. Every call that exercises one then requires a fresh human confirmation.
+
+```ruby
+use AgentAdmit::Middleware,
+    scope_for: "write:payments",
+    action_summary: ->(env) { "Pay Alex $50" }
+```
+
+The first call is refused with HTTP 403 and a `confirmation_required` body.
+The agent gives `confirmation.action_session_url` to the human. After the
+human confirms on AgentAdmit's hosted page with their passkey, the agent
+retries the same request with
+`X-AgentAdmit-Action-Attestation: <action_session_id>`.
+
+The SDK always forwards that header. A configured summary also causes the
+middleware to send a `sha256:` digest of the raw Rack body and the summary,
+then rewinds `rack.input` for the application. The hosted signature commits to
+the scope, method, endpoint, digest, and the words shown to the human.
+AgentAdmit proves what was shown but does not verify the summary against the
+request.
+
+Custom gates receive a typed `AgentAdmit::ConfirmationRequiredError` carrying
+the strictly parsed ceremony. Malformed ceremony blocks remain generic
+fail-closed `ActiveDenialError` instances with no link. On an accepted retry,
+`result.action_confirmation` and `env["agentadmit.action_confirmation"]`
+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.
@@ -407,6 +455,8 @@ 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 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.
+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/caller_consent.rb

@@ -137,11 +137,17 @@ module AgentAdmit
         # 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.
+        # The agent's confirm-each-time attestation (1.11.0) rides along
+        # whenever it is present, so a retry after a completed ceremony is
+        # accepted on this path too. This middleware declares no action
+        # summary, so it sends no request digest.
         result = @client.verify(token,
                                 scope_used: @required_scope,
                                 endpoint: env["PATH_INFO"],
                                 method: env["REQUEST_METHOD"],
-                                consent_first: true)
+                                consent_first: true,
+                                action_attestation_id:
+                                  IntrospectionClient.action_attestation_from_env(env))
       rescue InsufficientScopeError
         # Hosted consent-first ordering guarantees this refusal is reachable
         # only after consent was granted.
@@ -177,6 +183,9 @@ module AgentAdmit
       env["agentadmit.agent_label"] = result.agent_label
       env["agentadmit.presence"] = result.presence
       env["agentadmit.consent"] = consent
+      if result.action_confirmation
+        env["agentadmit.action_confirmation"] = result.action_confirmation
+      end
 
       @app.call(env)
     end

data/lib/agentadmit/config.rb

@@ -14,11 +14,21 @@ module AgentAdmit
 
     attr_reader :verify_url, :api_url
 
+    # One hosted-service origin, not two.
+    DEFAULT_API_URL    = "https://api.agentadmit.com"
+    DEFAULT_VERIFY_URL = "#{DEFAULT_API_URL}/api/v1/verify"
+    # Path appended to a non-default api_url to derive the verify URL.
+    VERIFY_PATH = "/api/v1/verify"
+
     def initialize
       @app_id = ENV.fetch("AGENTADMIT_APP_ID", "")
       @api_key = ENV.fetch("AGENTADMIT_API_KEY", "")
-      self.verify_url = ENV.fetch("AGENTADMIT_VERIFY_URL", "https://api.agentadmit.com/api/v1/verify")
-      self.api_url    = ENV.fetch("AGENTADMIT_API_URL", "https://api.agentadmit.com")
+      env_verify = ENV["AGENTADMIT_VERIFY_URL"]
+      self.verify_url = env_verify.nil? || env_verify.empty? ? DEFAULT_VERIFY_URL : env_verify
+      # An AGENTADMIT_VERIFY_URL left unset is not an explicit choice -- it
+      # must still follow a non-default api_url (see #api_url=).
+      @verify_url_explicit = !(env_verify.nil? || env_verify.empty?)
+      self.api_url = ENV.fetch("AGENTADMIT_API_URL", DEFAULT_API_URL)
       @token_prefix_access = "ag_at_"
       @token_prefix_connection = "ag_ct_"
       # Webhook signing secret (whsec_...) -- shown once when you configure the
@@ -28,14 +38,41 @@ module AgentAdmit
       @max_retries = ENV.fetch("AGENTADMIT_MAX_RETRIES", "3").to_i
     end
 
+    ##
+    # Set the /verify endpoint explicitly. An explicit verify URL always
+    # wins -- assigning it pins the endpoint, and a later api_url no longer
+    # derives over it.
+    #
     def verify_url=(url)
       validate_url!(url, :verify_url)
       @verify_url = url
+      @verify_url_explicit = true
     end
 
+    ##
+    # Set the hosted API origin. When the verify URL was never chosen
+    # explicitly, it FOLLOWS a non-default api_url.
+    #
+    # One hosted-service origin, not two: an operator who points api_url at a
+    # staging service or a local rig and leaves the verify URL alone expects
+    # verify to follow. Without this, the scope catalog and token operations
+    # go to one service while every per-call verify silently goes to
+    # production -- exactly the split caught on the TrainerTracer dogfood rig
+    # (Sep 3, 2026).
+    #
     def api_url=(url)
       validate_url!(url, :api_url)
       @api_url = url
+
+      return if @verify_url_explicit
+      return if url.nil? || url.empty?
+
+      origin = url.sub(%r{/\z}, "")
+      return if origin == DEFAULT_API_URL.sub(%r{/\z}, "")
+
+      derived = "#{origin}#{VERIFY_PATH}"
+      validate_url!(derived, :verify_url)
+      @verify_url = derived
     end
 
     ##

data/lib/agentadmit/introspection_client.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "json"
 require "uri"
+require "digest"
 
 module AgentAdmit
   ##
@@ -15,9 +16,22 @@ module AgentAdmit
     # Hard cap on cumulative wait across all retries of a single verify call.
     MAX_RETRY_BUDGET_MS = 120_000
 
+    # Confirm-each-time (1.11.0). Request header an agent sets on its retry
+    # after the human completed the hosted confirmation ceremony, and the
+    # Rack env key Rack exposes it under.
+    ACTION_ATTESTATION_HEADER   = "X-AgentAdmit-Action-Attestation"
+    ACTION_ATTESTATION_RACK_KEY = "HTTP_X_AGENTADMIT_ACTION_ATTESTATION"
+
+    # Hosted BodySchema caps on the verify route for the confirm-each-time
+    # fields (endpoint <=500 and method <=20 are enforced elsewhere).
+    ATTESTATION_MAX = 120
+    DIGEST_MAX      = 128
+    SUMMARY_MAX     = 200
+
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
                                      :sub, :role, :app_id, :jti, :exp, :consent,
-                                     :presence, :purpose, :user_intent, keyword_init: true) do
+                                     :presence, :purpose, :user_intent,
+                                     :action_confirmation, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -58,6 +72,105 @@ module AgentAdmit
       # user_intent is the user's). Review-time record only, never an
       # enforcement input; authorization decisions ride scopes, connection
       # status, and consent.
+
+      # `action_confirmation` (Hash or nil) is the confirm-each-time
+      # attestation the hosted service CONSUMED to accept this call:
+      # {"action_session_id" => String, "consumed" => true}. Present only
+      # when a fresh human confirmation was spent on exactly this action, and
+      # only when the block is strictly typed -- anything else is dropped. An
+      # app that runs its own transaction step-up can treat this as that
+      # confirmation instead of asking the human twice.
+      def action_confirmed?
+        action_confirmation.is_a?(Hash) && action_confirmation["consumed"] == true
+      end
+    end
+
+    class << self
+      ##
+      # `sha256:<hex>` over the RAW request body bytes, so a confirmation
+      # covers the exact payload and not merely the route. nil for an empty
+      # or absent body (the field is then omitted, never sent as null).
+      #
+      # @param body [String, nil] raw request body bytes
+      # @return [String, nil]
+      #
+      def request_digest_for(body)
+        return nil unless body.is_a?(String) && !body.empty?
+
+        "sha256:#{Digest::SHA256.hexdigest(body)}"
+      end
+
+      ##
+      # A strictly-typed copy of the wire `confirmation` block, or nil when
+      # it is malformed. ids/urls/expiry/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 `confirmation` value from the hosted response
+      # @return [Hash, nil]
+      #
+      def parse_action_confirmation(raw)
+        return nil unless raw.is_a?(Hash)
+        return nil unless %w[action_session_id action_session_url expires_at scope]
+                          .all? { |key| raw[key].is_a?(String) }
+
+        nullable = ->(value) { value.is_a?(String) ? value : nil }
+        { "action_session_id"  => raw["action_session_id"],
+          "action_session_url" => raw["action_session_url"],
+          "expires_at"         => raw["expires_at"],
+          "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 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
+      # or empty, so the field is omitted from the verify body.
+      #
+      # @param env [Hash] the Rack env
+      # @return [String, nil]
+      #
+      def action_attestation_from_env(env)
+        return nil unless env.is_a?(Hash)
+
+        raw = env[ACTION_ATTESTATION_RACK_KEY]
+        raw = raw.first if raw.is_a?(Array)
+        return nil unless raw.is_a?(String)
+
+        # Rack folds a repeated header into one comma-joined String; an
+        # attestation id is a single opaque value, so take the first.
+        value = raw.split(",").first.to_s.strip
+        value.empty? ? nil : value[0, ATTESTATION_MAX]
+      end
     end
 
     def initialize(config = nil)
@@ -83,15 +196,29 @@ module AgentAdmit
     #   truncated to 500 characters.
     # @param method [String, nil] inbound HTTP method; sent uppercased,
     #   capped at 20 characters.
+    # @param action_attestation_id [String, nil] confirm-each-time (1.11.0):
+    #   the single-use attestation id from a completed hosted ceremony, which
+    #   the agent presents on its retry via the
+    #   X-AgentAdmit-Action-Attestation header. Capped at 120 characters.
+    # @param request_digest [String, nil] `sha256:<hex>` over the raw request
+    #   body, so the confirmation covers the exact payload, not just the
+    #   route. Capped at 128 characters.
+    # @param action_summary [String, nil] the app's plain-language
+    #   description of THIS action, shown to the human on the hosted
+    #   confirmation page and committed into the signature. Trimmed and
+    #   capped at 200 characters. AgentAdmit does not verify the summary
+    #   against the request; it proves what the human was shown.
     # @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
+    #   {BoundExceededError}, {ConfirmationRequiredError}) 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, scope_used: nil, endpoint: nil, method: nil, consent_first: false)
+    def verify(token, scope_used: nil, endpoint: nil, method: nil, consent_first: false,
+               action_attestation_id: nil, request_digest: nil, action_summary: nil)
       unless token.start_with?(@config.token_prefix_access)
         raise InvalidTokenError, "Not an AgentAdmit access token"
       end
@@ -106,7 +233,10 @@ module AgentAdmit
       (0..max_retries).each do |attempt|
         request = build_request(uri, token, scope_used: scope_used,
                                 endpoint: endpoint, method: method,
-                                consent_first: consent_first)
+                                consent_first: consent_first,
+                                action_attestation_id: action_attestation_id,
+                                request_digest: request_digest,
+                                action_summary: action_summary)
 
         begin
           response = http.request(request)
@@ -219,6 +349,20 @@ module AgentAdmit
         user_intent = data["user_intent"]
         user_intent = nil unless user_intent.is_a?(String)
 
+        # Confirm-each-time (1.11.0): the confirmation this accepted call
+        # SPENT. Strict -- a String session id and a literal boolean true
+        # consumed flag, or the block is dropped entirely. Surfacing a
+        # half-formed block would let an app skip its own step-up on a
+        # confirmation that was never actually consumed.
+        action_confirmation = data["action_confirmation"]
+        action_confirmation =
+          if action_confirmation.is_a?(Hash) &&
+             action_confirmation["action_session_id"].is_a?(String) &&
+             action_confirmation["consumed"] == true
+            { "action_session_id" => action_confirmation["action_session_id"],
+              "consumed" => true }
+          end
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -232,7 +376,8 @@ module AgentAdmit
           consent:      consent,
           presence:     presence,
           purpose:      purpose,
-          user_intent:  user_intent
+          user_intent:  user_intent,
+          action_confirmation: action_confirmation
         )
       end
 
@@ -338,6 +483,15 @@ module AgentAdmit
     #    hosted response when present.
     #  - bound_exceeded: the hosted bounded-capabilities layer refused the
     #    call; hosted fields ride along verbatim on the error's data.
+    #  - confirmation_required: the scope IS granted but this call needs a
+    #    fresh human confirmation; the staged ceremony rides along, strictly
+    #    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)
@@ -356,6 +510,47 @@ module AgentAdmit
           data["error_description"] || "Call refused by the authorization service.",
           data: data
         )
+      when "confirmation_required"
+        confirmation = self.class.parse_action_confirmation(data["confirmation"])
+        if confirmation
+          description = data["error_description"]
+          description = ConfirmationRequiredError::DESCRIPTION unless
+            description.is_a?(String) && !description.empty?
+          status = data["attestation_status"]
+          raise ConfirmationRequiredError.new(
+            description,
+            confirmation: confirmation,
+            attestation_status: status.is_a?(String) ? status : nil,
+            data: data
+          )
+        end
+        # Malformed ceremony: fall through to the generic denial below.
+        raise ActiveDenialError.new(
+          "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.",
@@ -372,8 +567,13 @@ module AgentAdmit
     # 20). Unknown fields are OMITTED, never sent as null or empty string --
     # the hosted audit row then honestly records "not reported".
     #
+    # Confirm-each-time (1.11.0) adds three more optional fields under the
+    # same rule: action_attestation_id (<=120), request_digest (<=128) and
+    # action_summary (trimmed, <=200).
+    #
     def build_request(uri, token, scope_used: nil, endpoint: nil, method: nil,
-                      consent_first: false)
+                      consent_first: false, action_attestation_id: nil,
+                      request_digest: nil, action_summary: nil)
       req = Net::HTTP::Post.new(uri.path)
       req["Authorization"] = "Bearer #{@config.api_key}"
       req["Content-Type"]  = "application/json"
@@ -387,6 +587,13 @@ module AgentAdmit
       body[:method] = verb.upcase[0, 20] if verb
       body[:consent_first] = true if consent_first
 
+      attestation = trimmed_presence_of(action_attestation_id)
+      body[:action_attestation_id] = attestation[0, ATTESTATION_MAX] if attestation
+      digest = presence_of(request_digest)
+      body[:request_digest] = digest[0, DIGEST_MAX] if digest
+      summary = trimmed_presence_of(action_summary)
+      body[:action_summary] = summary[0, SUMMARY_MAX] if summary
+
       req.body = JSON.generate(body)
       req
     end
@@ -396,6 +603,12 @@ module AgentAdmit
       value.is_a?(String) && !value.empty? ? value : nil
     end
 
+    # Same, after stripping surrounding whitespace (agent-supplied header
+    # values and app-supplied summaries both arrive padded).
+    def trimmed_presence_of(value)
+      presence_of(value.is_a?(String) ? value.strip : 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.

data/lib/agentadmit/middleware.rb

@@ -12,6 +12,11 @@ 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.action_confirmation']
+  #                                   -- {"action_session_id" =>, "consumed" => true}
+  #                                      when a confirm-each-time confirmation
+  #                                      was spent on THIS call; key absent
+  #                                      otherwise
   #
   # Every verify call carries per-call audit telemetry: the request path
   # (PATH_INFO -- no query string) and the uppercase HTTP method, plus the
@@ -28,19 +33,45 @@ module AgentAdmit
   #
   # 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.
+  # call (insufficient_scope, bound_exceeded, confirmation_required, or an
+  # error code this SDK has never heard of). The middleware returns 403 and
+  # never calls the app.
+  #
+  # Confirm-each-time (1.11.0). The agent's
+  # X-AgentAdmit-Action-Attestation header is ALWAYS forwarded when present
+  # -- with or without an action summary. Declare an action summary to make
+  # a route confirm-each-time-ready: the middleware then also digests the
+  # raw request body and sends the human-readable summary, so the hosted
+  # ceremony (and the passkey signature) covers the exact payload:
+  #
+  #   use AgentAdmit::Middleware, scope_for: "write:payments",
+  #       action_summary: ->(env) { "Pay #{params(env)['trainer']} $#{params(env)['amount']}" }
+  #   # ... a static String, or a block, work too:
+  #   use AgentAdmit::Middleware, scope_for: "write:payments" do |env|
+  #     "Publish the draft post"
+  #   end
   #
   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, scope_for: nil)
+    ##
+    # @param app [#call] the downstream Rack app
+    # @param scope_for [Proc, String, nil] the scope this request enforces
+    # @param action_summary [Proc, String, nil] confirm-each-time (1.11.0):
+    #   the plain-language description of THIS action for the human ("Pay
+    #   Alex $50"). A Proc (env -> String or nil) or a static String; a block
+    #   is accepted as an alternative. Supplying one also turns on the raw
+    #   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)
       @app = app
       @client = IntrospectionClient.new
       @config = AgentAdmit.configuration || Config.new
       @scope_for = scope_for
+      @action_summary = action_summary || action_summary_block
     end
 
     def call(env)
@@ -54,13 +85,23 @@ module AgentAdmit
           result = @client.verify(token,
                                   scope_used: resolve_scope(env),
                                   endpoint: env["PATH_INFO"],
-                                  method: env["REQUEST_METHOD"])
+                                  method: env["REQUEST_METHOD"],
+                                  action_attestation_id:
+                                    IntrospectionClient.action_attestation_from_env(env),
+                                  request_digest: resolve_request_digest(env),
+                                  action_summary: resolve_action_summary(env))
           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
+          # 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.
+          if result.action_confirmation
+            env["agentadmit.action_confirmation"] = result.action_confirmation
+          end
         rescue ActiveDenialError => e
           # Token valid, call refused (active: true + error). Fail closed:
           # 403 with the denial's contract shape; the app never runs.
@@ -90,5 +131,42 @@ module AgentAdmit
 
       @scope_for
     end
+
+    ##
+    # The plain-language action summary for this request, when the app
+    # declared one at mount time. A Proc (env -> String or nil) or a static
+    # String. A summary is telemetry for the human's confirmation page, never
+    # an authorization input, so a callback that raises must not turn a
+    # legitimate call into an error: it degrades to no summary.
+    #
+    def resolve_action_summary(env)
+      return nil unless @action_summary
+
+      summary = @action_summary.respond_to?(:call) ? @action_summary.call(env) : @action_summary
+      summary.is_a?(String) ? summary : nil
+    rescue StandardError
+      nil
+    end
+
+    ##
+    # `sha256:<hex>` over the RAW request body, computed only for a
+    # middleware configured with an action summary (a confirm-each-time
+    # route) -- the confirmation must cover the exact payload, not just the
+    # route. The body is rewound afterwards so the downstream app still reads
+    # it; a body this middleware cannot read simply yields no digest.
+    #
+    def resolve_request_digest(env)
+      return nil unless @action_summary
+
+      input = env["rack.input"]
+      return nil unless input.respond_to?(:read)
+
+      input.rewind if input.respond_to?(:rewind)
+      raw = input.read
+      input.rewind if input.respond_to?(:rewind)
+      IntrospectionClient.request_digest_for(raw)
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/agentadmit/scope_enforcement.rb

@@ -87,6 +87,11 @@ module AgentAdmit
         connection_id: request.env["agentadmit.connection_id"],
         agent_label: request.env["agentadmit.agent_label"],
         presence: request.env["agentadmit.presence"],
+        # Confirm-each-time (1.11.0): the confirmation the hosted service
+        # spent to accept THIS call, or nil. An app running its own
+        # transaction step-up can treat a present block as that confirmation
+        # instead of asking the human twice.
+        action_confirmation: request.env["agentadmit.action_confirmation"],
       }
     end
   end

data/lib/agentadmit/version.rb

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

data/lib/agentadmit.rb

@@ -98,6 +98,114 @@ module AgentAdmit
     end
   end
 
+  ##
+  # `active: true` + `error: "confirmation_required"` (SDK 1.11.0,
+  # confirm-each-time) -- the scope IS granted, but THIS call needs a fresh
+  # human confirmation before it may run. The hosted service has staged a
+  # one-time ceremony for exactly this action; {#confirmation} is the
+  # strictly-typed block describing it.
+  #
+  # The agent hands `confirmation["action_session_url"]` to the human. Only a
+  # user-verified passkey on that hosted page produces an attestation; the
+  # agent cannot complete the ceremony itself. The agent then retries the
+  # SAME request with the header
+  # `X-AgentAdmit-Action-Attestation: <action_session_id>`, which the SDK
+  # forwards as `action_attestation_id` on the next verify.
+  #
+  # {#attestation_status} explains why a presented attestation was NOT
+  # accepted, when one was presented (e.g. already_consumed, action_mismatch,
+  # expired, not_confirmed).
+  #
+  # A malformed confirmation block never reaches this class: the client falls
+  # back to a generic {ActiveDenialError} (fail closed, 403, no confirmation
+  # block) rather than relaying an unusable ceremony.
+  #
+  class ConfirmationRequiredError < ActiveDenialError
+    # The canonical agent-facing description. The hosted `error_description`
+    # wins when the service sends one.
+    DESCRIPTION = "This action requires a fresh human confirmation. " \
+                  "Give the confirmation link to the user, then retry with " \
+                  "the X-AgentAdmit-Action-Attestation header."
+
+    # @return [Hash] the strictly-typed staged ceremony: action_session_id,
+    #   action_session_url, expires_at, scope (Strings), and method, endpoint,
+    #   request_digest, summary (String or nil).
+    attr_reader :confirmation
+    # @return [String, nil] why a presented attestation was not accepted.
+    attr_reader :attestation_status
+
+    def initialize(message = DESCRIPTION, confirmation:, attestation_status: nil, data: {})
+      super(message, code: "confirmation_required", data: data)
+      @confirmation = confirmation
+      @attestation_status = attestation_status
+    end
+
+    # The 403 body: the refusal, the human-readable description, the staged
+    # ceremony, 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_required",
+               "error_description" => message,
+               "confirmation" => confirmation }
+      %w[attestation_status attestation_description renewal].each do |field|
+        body[field] = data[field] if data[field].is_a?(String)
+      end
+      body
+    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.10.1
+  version: 1.12.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json