agentadmit 1.5.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 810b958cd0fd3558a19bfc79910e194e45e02d95331b98747ff4edf29e337d8a
-  data.tar.gz: 4c18ad2b306eea918107543eeee24c3f2eb7f30010bfb3c1bb6502bcfa94718b
+  metadata.gz: 9903cf0e0365cc82696a35748e5736582e4d2e9aad33e9c956c62df61c4c5eea
+  data.tar.gz: e1cbbc38ef3ca551b003574383e759056f3c6f90c2224fc4cd8dc68af836c270
 SHA512:
-  metadata.gz: 4a0a65b2ce47a30683c14de7c397bea637adbe18ed76db7b8b579c5835d5dcdb90881ef93e20c687710cc37184ec3fc796a9fd153e1f6bf19edcb8f1c2875463
-  data.tar.gz: b81a5431a0a2b37728e675963ab79e188e5d0e288f4bb2a4e8497fe5df81ba7a962fc15d99b36fd21d72fa6472de266bb2dacef92aab79f46c04b615bcd31e58
+  metadata.gz: c3089318cad6fd8c1914a3f087b9e9e2351ee0131b81d6bd288a9fa736868ce6c64937de4a248c0c3c4162c2d4b481e044ef2c642d917d368499e42dd6a72e93
+  data.tar.gz: 2f2d55a5ea98bc761ccabd6cce0e3e5ac417b0b5b659094c05ca74178abd77752e392c6b6104621ab750ba97aa1264f5b4d541e47c4a243e20b037b1417b69ab

data/README.md

@@ -258,7 +258,7 @@ config = alerts.get_alert_config(app_id: 'app_abc123')
 AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes connections. **How you notify your own users is up to you.** AgentAdmit provides the data -- you deliver it through your own system (in-app notifications, email, push, etc.).
 
 - **Poll alerts** -- Use the SDK methods above from your backend to check for new events, then notify users through your existing system.
-- **Webhook delivery** -- Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit POSTs the payload to your server, signed with your `whsec_...` secret. Always verify the signature against the raw request body before trusting the payload:
+- **Webhook delivery** -- Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit POSTs the payload to your server, signed with your `whsec_...` secret. The payload carries `alert_id`, `alert_type`, `severity`, the connection's `agent_label`, and the grant's declared `purpose`; the full shape is documented in the Webhook Delivery section of the MCP guide at https://agentadmit.com/docs/mcp-guide. Always verify the signature against the raw request body before trusting the payload:
 
   ```ruby
   # Rails controller
@@ -302,3 +302,50 @@ 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.
+
+### User-declared intent
+
+User-declared intent: the user's OWN words, typed at the consent moment. `purpose` is the app's words for why the connection exists; `user_intent` is what the user actually said they wanted ("build me a weekly workout summary"). On the hosted consent page the user can type it into an optional field; apps collecting consent in their own UI can pass it at token issuance.
+
+Pass it when issuing a connection token (optional, 1-300 characters; a malformed value -- non-string, empty, or over 300 characters -- normalizes to `nil` and is omitted from the request rather than rejected):
+
+```ruby
+issued = tokens.issue_token(
+  user_id: "user_42",
+  scopes: ["read:orders"],
+  purpose: "Book quarterly travel for the sales team",
+  user_intent: "Book my flights to the Austin offsite in October"
+)
+```
+
+It flows exactly like purpose: stored on the connection, returned by verify, stamped into every audit row, and carried on grant and revocation ledger events. When the hosted presence ceremony runs, the user's own words are included in the verifiable-consent-evidence commitment, so their authenticator signs what they said they wanted.
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(token)
+result.user_intent # => "Book my flights to the Austin offsite in October" or nil
+```
+
+`user_intent` is nullable -- connections issued without one (or by servers that predate the field) read as `nil`. Months later, a review screen can answer "is this still appropriate?" with the user's own stated boundary, not just the app's. Like purpose, it is a review-time record and never an enforcement input; authorization decisions ride 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, :user_intent, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -47,6 +47,17 @@ 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.
+
+      # `user_intent` (String or nil) is the user-declared intent: the user's
+      # OWN words, typed at the consent moment (purpose is the app's words;
+      # user_intent is the user's). Review-time record only, never an
+      # enforcement input; authorization decisions ride scopes, connection
+      # status, and consent.
     end
 
     def initialize(config = nil)
@@ -177,6 +188,18 @@ 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)
+
+        # User-declared intent passes through the same way (the hosted
+        # /verify returns it nullable). Review-time record, never an
+        # enforcement input, so a malformed value is simply dropped.
+        user_intent = data["user_intent"]
+        user_intent = nil unless user_intent.is_a?(String)
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -188,7 +211,9 @@ module AgentAdmit
           jti:          data["jti"],
           exp:          data["exp"],
           consent:      consent,
-          presence:     presence
+          presence:     presence,
+          purpose:      purpose,
+          user_intent:  user_intent
         )
       end
 

data/lib/agentadmit/tokens_client.rb

@@ -15,6 +15,13 @@ 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
+
+    # Maximum length of a user-declared intent (matches the hosted API
+    # contract: optional string, 1..300 characters).
+    USER_INTENT_MAX_LENGTH = 300
+
     def initialize(config = nil)
       @config = config || AgentAdmit.configuration || Config.new
       @config.validate_api_key!
@@ -34,13 +41,46 @@ 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.
+    # @param user_intent [String, nil] user-declared intent: the user's OWN
+    #   words, typed at the consent moment (distinct from purpose, which is
+    #   the app's words). Optional, 1-300 characters. Validated like purpose:
+    #   a non-String, non-nil value or a string over 300 characters raises
+    #   ArgumentError before any request is sent — silently discarding the
+    #   user's typed words would be data loss. Empty/whitespace-only strings
+    #   normalize to nil and are omitted. Like purpose, it is a review-time
+    #   record, never an enforcement input.
     # @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, or if
+    #   user_intent is a non-String (other than nil) or 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,
+                    user_intent: nil)
+      if purpose && purpose.length > PURPOSE_MAX_LENGTH
+        raise ArgumentError, "purpose must be at most #{PURPOSE_MAX_LENGTH} characters"
+      end
+
+      # User-declared intent is validated like purpose: reject out-of-contract
+      # values before any request rather than silently discarding the user's
+      # typed words (data loss). Empty/whitespace-only normalizes to nil-omit.
+      unless user_intent.nil? || user_intent.is_a?(String)
+        raise ArgumentError, "user_intent must be a String or nil"
+      end
+      if user_intent && user_intent.length > USER_INTENT_MAX_LENGTH
+        raise ArgumentError, "user_intent must be at most #{USER_INTENT_MAX_LENGTH} characters"
+      end
+      user_intent = nil if user_intent && user_intent.strip.empty?
+
       body = { "user_id" => user_id, "scopes" => scopes }
       body["role"] = role if role
+      body["purpose"] = purpose if purpose
+      body["user_intent"] = user_intent if user_intent
       # 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.8.0"
 end

metadata

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