agentadmit 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 885a1ed3458153db1420a5b58acf902aafecdea120ef3e51ce238c25e635562a
-  data.tar.gz: d0477df5f1302c204fb751a28343a8986ed964e18c814f5b72abfb274037a1e3
+  metadata.gz: 810b958cd0fd3558a19bfc79910e194e45e02d95331b98747ff4edf29e337d8a
+  data.tar.gz: 4c18ad2b306eea918107543eeee24c3f2eb7f30010bfb3c1bb6502bcfa94718b
 SHA512:
-  metadata.gz: ad67e5e7b68872e5f9004e0da11b22d5ce7337f56725338fa9678e209e8689706f135fd0b4cd5eb042760944826757bcfc372f9dbbd223eb94a853e6692cbd75
-  data.tar.gz: 27780e1514e4296eba0aa2e345b888de8cbc74e44326ebbec4c3e0abd694c0026862387987b9264774bee8edffa125b44faf19b12e43d85cb36816bac7322c18
+  metadata.gz: 4a0a65b2ce47a30683c14de7c397bea637adbe18ed76db7b8b579c5835d5dcdb90881ef93e20c687710cc37184ec3fc796a9fd153e1f6bf19edcb8f1c2875463
+  data.tar.gz: b81a5431a0a2b37728e675963ab79e188e5d0e288f4bb2a4e8497fe5df81ba7a962fc15d99b36fd21d72fa6472de266bb2dacef92aab79f46c04b615bcd31e58

data/README.md

@@ -76,15 +76,24 @@ The token goes to the human, not the agent. No automated delivery = no prompt in
 
 AgentAdmit can host per-user consent switches for three independent caller classes: `human_session`, `in_app_ai`, and `external_agent`. No class's setting implies another's.
 
-**External agents:** the verify result already carries the verdict:
+**External agents:** the verify result already carries the verdict. The hosted service deliberately omits the verdict when its consent store is unreadable (degraded mode), so an absent verdict is *unresolved*, never a grant — `consent_granted?` fails closed on it. Resolve an absent or malformed verdict through the ledger:
 
 ```ruby
-result = AgentAdmit::IntrospectionClient.new.verify(token)
-unless result.consent_granted?
+client = AgentAdmit::IntrospectionClient.new
+result = client.verify(token)
+consent = result.consent
+unless consent.is_a?(Hash) && [true, false].include?(consent["granted"])
+  # absent/malformed verdict: the ledger holds the authoritative answer
+  consent = client.check_consent(app_user_id: result.user_id,
+                                 caller_class: "external_agent") # fail closed on error
+end
+unless consent["granted"] == true
   # the data owner has switched external agents off: return your own 403
 end
 ```
 
+The `AgentAdmit::CallerConsent` middleware does all of this for you: it evaluates the consent verdict **before** the scope check (a caller whose class the owner denied learns nothing about scope state) and resolves an absent verdict through the Consent Ledger, fail-closed.
+
 **Human sessions and in-app AI** never hold AgentAdmit tokens, so ask directly:
 
 ```ruby

data/lib/agentadmit/caller_consent.rb

@@ -18,7 +18,9 @@ module AgentAdmit
   #
   #  - external_agent: an ag_at_ access token -> hosted introspection, which
   #    returns the external-agent consent verdict inline plus the granted
-  #    scopes. Enforced here directly.
+  #    scopes. Consent is evaluated BEFORE scope (a denied class must not
+  #    learn scope state). A missing or malformed verdict is resolved through
+  #    the Consent Ledger, fail-closed -- absence is never a grant.
   #  - in_app_ai: your application's own server-side AI code path -> the
   #    Consent Ledger /consent/check for the in-app-AI class.
   #  - human_session: your application's own permission model (sharing,
@@ -121,8 +123,12 @@ module AgentAdmit
 
     ##
     # External-agent path: hosted introspection carries the verdict and the
-    # scopes. A present-and-denied verdict fails closed; an absent verdict
-    # means the platform default (external-agent allowed) held.
+    # scopes. Consent is evaluated first (Patent FIG. 3: the class consent
+    # decision precedes scope evaluation) -- checking scope first would leak
+    # granted-scope state to callers whose class the owner has denied. The
+    # hosted service omits the verdict when its consent-store read fails
+    # (designed degraded mode), so an absent or malformed verdict is resolved
+    # through the Consent Ledger, fail-closed -- never treated as a grant.
     #
     def call_external_agent(env)
       token = (env["HTTP_AUTHORIZATION"] || "").sub(/\Abearer /i, "")
@@ -135,6 +141,27 @@ module AgentAdmit
         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
+
       if @required_scope && !(result.scopes || []).include?(@required_scope)
         return [403, { "Content-Type" => "application/json" },
                 [{ error: "insufficient_scope",
@@ -143,16 +170,13 @@ module AgentAdmit
                    message: "This action requires '#{@required_scope}' scope." }.to_json]]
       end
 
-      return json_error(403, "consent_not_granted",
-                        "The data owner has not enabled external agent access.") unless result.consent_granted?
-
       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
-      env["agentadmit.consent"] = result.consent if result.consent
+      env["agentadmit.consent"] = consent
 
       @app.call(env)
     end

data/lib/agentadmit/introspection_client.rb

@@ -26,22 +26,24 @@ module AgentAdmit
       # nil). A denied verdict means the app returns its own 403 -- the token
       # itself stays valid (consent is orthogonal to revocation).
       #
-      # Contract (matches the PHP and Java SDKs): an ABSENT consent block
-      # means a legacy server that never sends one -- treated as allowed,
-      # which is also the platform default for the external-agent class. A
-      # PRESENT block grants only on an explicit boolean true; a missing or
-      # non-boolean granted value is treated as denied (malformed = deny).
+      # Contract: grants ONLY on an explicit boolean true. An ABSENT block is
+      # NEVER a grant -- the hosted service deliberately omits it when its
+      # consent-store read fails (designed degraded mode), so absence here
+      # fails closed. A missing or non-boolean granted value is likewise
+      # denied (malformed = deny). Callers that want the authoritative answer
+      # for an absent/malformed verdict should resolve it through
+      # #check_consent for the external_agent class (CallerConsent does this
+      # automatically).
       def consent_granted?
-        return true if consent.nil?
-        consent["granted"] == true
+        consent.is_a?(Hash) && consent["granted"] == true
       end
 
       # Human-presence fact from the WebAuthn step-up (additive; may be nil).
       # True ONLY when the connection was authorized by a human who completed
       # a presence ceremony on the consent page: verified must be the boolean
-      # true. Unlike consent, absence fails closed -- older servers never send
-      # the block, and connections minted without a ceremony carry
-      # verified: false, so nil/false/malformed all read as not verified.
+      # true. Absence fails closed -- older servers never send the block, and
+      # connections minted without a ceremony carry verified: false, so
+      # nil/false/malformed all read as not verified.
       def presence_verified?
         presence.is_a?(Hash) && presence["verified"] == true
       end
@@ -161,17 +163,17 @@ module AgentAdmit
         # Validate that consumed fields have the expected types when present.
         validate_introspection_types!(data)
 
-        # Keep any PRESENT consent hash, even with a malformed granted value:
-        # coercing it to nil would read as "legacy server, allowed" in
-        # consent_granted?, silently failing open. A malformed verdict must
-        # stay visible so consent_granted? can deny it.
+        # Keep the consent block only when it is a Hash; anything else reads
+        # as nil. Absent and malformed are both safe: neither is ever a grant
+        # (consent_granted? fails closed, and CallerConsent resolves the
+        # authoritative verdict through the Consent Ledger).
         consent = data["consent"]
         consent = nil unless consent.is_a?(Hash)
 
         # Presence rides along when the platform returns it. Same strictness
         # as active: verified must be the boolean true or false, never coerced.
-        # Unlike consent, a malformed block is dropped -- presence_verified?
-        # fails closed on nil, so dropping cannot fail open.
+        # A malformed block is dropped -- presence_verified? fails closed on
+        # nil, so dropping cannot fail open.
         presence = data["presence"]
         presence = nil unless presence.is_a?(Hash) && [true, false].include?(presence["verified"])
 

data/lib/agentadmit/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json