agentadmit 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 885a1ed3458153db1420a5b58acf902aafecdea120ef3e51ce238c25e635562a
-  data.tar.gz: d0477df5f1302c204fb751a28343a8986ed964e18c814f5b72abfb274037a1e3
+  metadata.gz: 53205cacbbf7942a6cb2600c9cea4c0c739d991be95bd7c627df405287e5f52c
+  data.tar.gz: b9849673334811698875c9733abc1b69c2938111cf4b928cde741cb0e6ba6d0f
 SHA512:
-  metadata.gz: ad67e5e7b68872e5f9004e0da11b22d5ce7337f56725338fa9678e209e8689706f135fd0b4cd5eb042760944826757bcfc372f9dbbd223eb94a853e6692cbd75
-  data.tar.gz: 27780e1514e4296eba0aa2e345b888de8cbc74e44326ebbec4c3e0abd694c0026862387987b9264774bee8edffa125b44faf19b12e43d85cb36816bac7322c18
+  metadata.gz: ed8c4e40cc18a7749257674d2ba0fba6d8fb79946aeb868cf84fa5f5fa67075eff3cc80456e67e34886157f63cbaaceb1156abc3ce92f87a3400096920354f69
+  data.tar.gz: e184a592c70ac59b82f906f00a7cae3c83ecd3b9681e5a35421bad55c3979a11bbfbfe45f85f8135fe4a909ed1f1c394108b03d86b199f91bf999ac8cf40e1bc

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
@@ -293,3 +302,26 @@ granted = tokens.exchange(connection_token, agent_label: "MyAssistant")
 # Revoke when the user disconnects the agent.
 tokens.revoke(granted["connection_id"], reason: "user_requested")
 ```
+
+### Declared purpose
+
+Declared purpose: the user-facing reason recorded on the grant at the consent moment. Review-time record only, never an enforcement input; authorization decisions ride scopes, connection status, and consent.
+
+Pass it when issuing a connection token (optional, max 300 characters; omitted from the request when `nil`):
+
+```ruby
+issued = tokens.issue_token(
+  user_id: "user_42",
+  scopes: ["read:orders"],
+  purpose: "Book quarterly travel for the sales team"
+)
+```
+
+The verify result carries it back for display in dashboards, review screens, and audit views:
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(token)
+result.purpose # => "Book quarterly travel for the sales team" or nil
+```
+
+`purpose` is nullable -- connections issued without one (or by servers that predate the field) read as `nil`. Do not branch authorization on it; keep enforcement on scopes, connection status, and consent.

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

@@ -17,7 +17,7 @@ module AgentAdmit
 
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
                                      :sub, :role, :app_id, :jti, :exp, :consent,
-                                     :presence, keyword_init: true) do
+                                     :presence, :purpose, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -26,25 +26,32 @@ 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
+
+      # `purpose` (String or nil) is the declared purpose: the user-facing
+      # reason recorded on the grant at the consent moment. Review-time record
+      # only, never an enforcement input; authorization decisions ride scopes,
+      # connection status, and consent.
     end
 
     def initialize(config = nil)
@@ -161,20 +168,26 @@ 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"])
 
+        # Declared purpose passes through as-is when it is a String (the
+        # hosted /verify returns it nullable). It is a review-time record,
+        # never an enforcement input, so a malformed value is simply dropped.
+        purpose = data["purpose"]
+        purpose = nil unless purpose.is_a?(String)
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -186,7 +199,8 @@ module AgentAdmit
           jti:          data["jti"],
           exp:          data["exp"],
           consent:      consent,
-          presence:     presence
+          presence:     presence,
+          purpose:      purpose
         )
       end
 

data/lib/agentadmit/tokens_client.rb

@@ -15,6 +15,9 @@ module AgentAdmit
     # instead for an until-revoked connection (explicit JSON null).
     UNSET = Object.new.freeze
 
+    # Maximum length of a declared purpose (matches the hosted API contract).
+    PURPOSE_MAX_LENGTH = 300
+
     def initialize(config = nil)
       @config = config || AgentAdmit.configuration || Config.new
       @config.validate_api_key!
@@ -34,13 +37,24 @@ module AgentAdmit
     # @param scopes [Array<String>] scopes the connection grants
     # @param role [String, nil] the user's role on the connection
     # @param duration_seconds [Integer, nil, UNSET] see above
+    # @param purpose [String, nil] declared purpose: the user-facing reason
+    #   recorded on the grant at the consent moment. Review-time record only,
+    #   never an enforcement input; authorization decisions ride scopes,
+    #   connection status, and consent. Max 300 characters; omitted from the
+    #   request when nil.
     # @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
     # @raise [IntrospectionError] if issuance fails
     #
-    def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET)
+    def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET, purpose: nil)
+      if purpose && purpose.length > PURPOSE_MAX_LENGTH
+        raise ArgumentError, "purpose must be at most #{PURPOSE_MAX_LENGTH} characters"
+      end
+
       body = { "user_id" => user_id, "scopes" => scopes }
       body["role"] = role if role
+      body["purpose"] = purpose if purpose
       # 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.5.0"
+  VERSION = "1.7.0"
 end

metadata

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