agentadmit 1.5.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 810b958cd0fd3558a19bfc79910e194e45e02d95331b98747ff4edf29e337d8a
-  data.tar.gz: 4c18ad2b306eea918107543eeee24c3f2eb7f30010bfb3c1bb6502bcfa94718b
+  metadata.gz: 53205cacbbf7942a6cb2600c9cea4c0c739d991be95bd7c627df405287e5f52c
+  data.tar.gz: b9849673334811698875c9733abc1b69c2938111cf4b928cde741cb0e6ba6d0f
 SHA512:
-  metadata.gz: 4a0a65b2ce47a30683c14de7c397bea637adbe18ed76db7b8b579c5835d5dcdb90881ef93e20c687710cc37184ec3fc796a9fd153e1f6bf19edcb8f1c2875463
-  data.tar.gz: b81a5431a0a2b37728e675963ab79e188e5d0e288f4bb2a4e8497fe5df81ba7a962fc15d99b36fd21d72fa6472de266bb2dacef92aab79f46c04b615bcd31e58
+  metadata.gz: ed8c4e40cc18a7749257674d2ba0fba6d8fb79946aeb868cf84fa5f5fa67075eff3cc80456e67e34886157f63cbaaceb1156abc3ce92f87a3400096920354f69
+  data.tar.gz: e184a592c70ac59b82f906f00a7cae3c83ecd3b9681e5a35421bad55c3979a11bbfbfe45f85f8135fe4a909ed1f1c394108b03d86b199f91bf999ac8cf40e1bc

data/README.md

@@ -302,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/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
@@ -47,6 +47,11 @@ module AgentAdmit
       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)
@@ -177,6 +182,12 @@ module AgentAdmit
         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"],
@@ -188,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.1"
+  VERSION = "1.7.0"
 end

metadata

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