agentadmit 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53205cacbbf7942a6cb2600c9cea4c0c739d991be95bd7c627df405287e5f52c
-  data.tar.gz: b9849673334811698875c9733abc1b69c2938111cf4b928cde741cb0e6ba6d0f
+  metadata.gz: 677087b98e731945e7485c16db8c8a858dabc54fa346565b3697948db26f9fcb
+  data.tar.gz: 189ff20ab78520f0ae0ce4a7db1cd32ba8067153c5c5787f4cd04984730eece3
 SHA512:
-  metadata.gz: ed8c4e40cc18a7749257674d2ba0fba6d8fb79946aeb868cf84fa5f5fa67075eff3cc80456e67e34886157f63cbaaceb1156abc3ce92f87a3400096920354f69
-  data.tar.gz: e184a592c70ac59b82f906f00a7cae3c83ecd3b9681e5a35421bad55c3979a11bbfbfe45f85f8135fe4a909ed1f1c394108b03d86b199f91bf999ac8cf40e1bc
+  metadata.gz: 4e374766292936272c50ca95fd2b63ae97f5cb044d194a879dc268009e453630406e090fb57227dcb3dc19f964a04ec3c12dd7b40500cbfd1f1f6b218771e7cc
+  data.tar.gz: c18398441c0d63526cb6fce609907eea627830a7dc71803688542a29950d8b0cf7ed1bd9d30dc3c0be3c154f53ba4f568707b855c3e01e001f5cdbc7ed9a1ff6

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
@@ -325,3 +325,46 @@ 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.
+
+## App-Attested Presence
+
+If your app gates token minting behind its own embedded passkey/WebAuthn ceremony, AgentAdmit never witnesses that ceremony (it is origin-bound), so by default the hosted service reports `presence.verified: false` for those connections. Attest the ceremony fact at issuance to close that gap -- AFTER verifying and consuming your own fresh, purpose-bound attestation:
+
+```ruby
+issued = tokens.issue_token(
+  user_id: "user_42",
+  scopes: ["read:orders"],
+  presence: AgentAdmit::AppAttestedPresence.new(
+    method: "my_webauthn",             # lowercase alphanumeric/underscore
+    verified_at: attestation.created_at # Time or DateTime
+  )
+)
+```
+
+The SDK sends it as `presence: {verified: true, uv: true, method, verified_at}` -- `verified`/`uv` are literal true by construction and the class cannot represent anything else; a raw Hash is rejected so the wire contract stays owned by the typed class. The hosted service validates freshness (10-minute window, 60 s future clock-skew slack) and stores the method provenance-marked `app:<method>` so app-attested facts stay distinct from ceremonies AgentAdmit witnessed itself. Introspection, the grant-event ledger, and the evidence API then carry `presence.verified: true` for the connection.
+
+Honesty ceiling: this is your app's attestation, recorded and provenance-marked. It is not witnessed by AgentAdmit and not independently verifiable. Only attest a ceremony that verified the user with UV (biometric or PIN user verification); a ceremony without UV carries no presence fact, so pass `nil` (the default). An out-of-contract method (`^[a-z0-9_]+$`, 1-60) raises `ArgumentError` at construction, before any request; Ruby `Time`/`DateTime` always carry an offset, so `verified_at` serializes RFC 3339 with an explicit offset by construction.

data/lib/agentadmit/app_attested_presence.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "time"
+
+module AgentAdmit
+  ##
+  # App-attested presence: a ceremony fact your app attests at token issuance.
+  #
+  # Pass an instance to TokensClient#issue_token AFTER verifying and consuming
+  # your app's own fresh, purpose-bound WebAuthn/passkey attestation for the
+  # mint. The SDK forwards it to the hosted mint as
+  # presence {verified: true, uv: true, method, verified_at}; the hosted
+  # service stores it method-prefixed "app:<method>" — the provenance marker
+  # that keeps app-attested facts distinct from hosted-witnessed ceremonies.
+  #
+  # Honesty ceiling: this is YOUR attestation, recorded and provenance-marked.
+  # It is not witnessed by AgentAdmit and not independently verifiable. Only
+  # construct one for a ceremony that verified the user with UV (biometric or
+  # PIN user verification); verified/uv serialize as literal true and cannot
+  # represent anything else — a ceremony without UV carries no presence fact,
+  # so simply pass nil.
+  #
+  # verified_at must be recent: the hosted service enforces a 10-minute
+  # freshness window with 60 seconds of future clock-skew slack. Ruby Time and
+  # DateTime always carry an offset, so #iso8601 serializes RFC 3339 with an
+  # explicit offset by construction (the hosted contract; offset-less
+  # timestamps are rejected with 400).
+  #
+  class AppAttestedPresence
+    METHOD_PATTERN = /\A[a-z0-9_]+\z/
+    METHOD_MAX_LENGTH = 60
+
+    # NOTE: a +method+ reader shadows Object#method on instances — the same
+    # trade stdlib's Net::HTTPGenericRequest makes; the name matches the wire
+    # field.
+    attr_reader :method, :verified_at
+
+    ##
+    # @param method [String] your ceremony mechanism, 1-60 lowercase
+    #   alphanumeric/underscore characters (e.g. "my_webauthn")
+    # @param verified_at [Time, DateTime] when the ceremony completed
+    # @raise [ArgumentError] when method is out of contract or verified_at is
+    #   not a timestamp — validated at construction, before any request,
+    #   where the fix is obvious
+    #
+    def initialize(method:, verified_at:)
+      unless method.is_a?(String) && !method.empty? &&
+             method.length <= METHOD_MAX_LENGTH && METHOD_PATTERN.match?(method)
+        raise ArgumentError,
+              "method must be 1-#{METHOD_MAX_LENGTH} lowercase alphanumeric/underscore " \
+              "characters (e.g. 'my_webauthn')"
+      end
+      unless verified_at.respond_to?(:iso8601)
+        raise ArgumentError,
+              "verified_at must be a Time or DateTime (the ceremony that authorized " \
+              "this mint just happened)"
+      end
+
+      @method = method
+      @verified_at = verified_at
+    end
+
+    ##
+    # The exact JSON object forwarded to the hosted mint.
+    #
+    # @return [Hash]
+    #
+    def to_wire
+      {
+        "verified" => true,
+        "uv" => true,
+        "method" => @method,
+        "verified_at" => @verified_at.iso8601
+      }
+    end
+  end
+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, :purpose, keyword_init: true) do
+                                     :presence, :purpose, :user_intent, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -52,6 +52,12 @@ module AgentAdmit
       # 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)
@@ -188,6 +194,12 @@ module AgentAdmit
         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"],
@@ -200,7 +212,8 @@ module AgentAdmit
           exp:          data["exp"],
           consent:      consent,
           presence:     presence,
-          purpose:      purpose
+          purpose:      purpose,
+          user_intent:  user_intent
         )
       end
 

data/lib/agentadmit/tokens_client.rb

@@ -18,6 +18,10 @@ module AgentAdmit
     # 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!
@@ -42,19 +46,56 @@ module AgentAdmit
     #   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.
+    # @param presence [AppAttestedPresence, nil] app-attested ceremony fact:
+    #   set it AFTER verifying and consuming your app's own fresh,
+    #   purpose-bound WebAuthn/passkey attestation for this mint. Forwarded
+    #   as presence {verified: true, uv: true, method, verified_at} and
+    #   stored provenance-marked "app:<method>"; omitted when nil (omitting
+    #   the field is the only way to say "no ceremony").
     # @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 [ArgumentError] if purpose exceeds 300 characters, if
+    #   user_intent is a non-String (other than nil) or exceeds 300
+    #   characters, or if presence is neither nil nor an AppAttestedPresence
     # @raise [IntrospectionError] if issuance fails
     #
-    def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET, purpose: nil)
+    def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET, purpose: nil,
+                    user_intent: nil, presence: 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?
+
+      # Presence is typed-only: a raw Hash is rejected so the wire contract
+      # (literal-true verified/uv, offset-carrying verified_at) stays owned
+      # by AppAttestedPresence, never hand-rolled at call sites.
+      unless presence.nil? || presence.is_a?(AppAttestedPresence)
+        raise ArgumentError, "presence must be an AgentAdmit::AppAttestedPresence or nil"
+      end
+
       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
+      body["presence"] = presence.to_wire if presence
       # 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.7.0"
+  VERSION = "1.9.0"
 end

data/lib/agentadmit.rb

@@ -88,6 +88,7 @@ end
 
 require_relative "agentadmit/config"
 require_relative "agentadmit/introspection_client"
+require_relative "agentadmit/app_attested_presence"
 require_relative "agentadmit/tokens_client"
 require_relative "agentadmit/alerts_client"
 require_relative "agentadmit/webhook"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -35,6 +35,7 @@ files:
 - README.md
 - lib/agentadmit.rb
 - lib/agentadmit/alerts_client.rb
+- lib/agentadmit/app_attested_presence.rb
 - lib/agentadmit/caller_consent.rb
 - lib/agentadmit/config.rb
 - lib/agentadmit/introspection_client.rb