agentadmit 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9903cf0e0365cc82696a35748e5736582e4d2e9aad33e9c956c62df61c4c5eea
-  data.tar.gz: e1cbbc38ef3ca551b003574383e759056f3c6f90c2224fc4cd8dc68af836c270
+  metadata.gz: 677087b98e731945e7485c16db8c8a858dabc54fa346565b3697948db26f9fcb
+  data.tar.gz: 189ff20ab78520f0ae0ce4a7db1cd32ba8067153c5c5787f4cd04984730eece3
 SHA512:
-  metadata.gz: c3089318cad6fd8c1914a3f087b9e9e2351ee0131b81d6bd288a9fa736868ce6c64937de4a248c0c3c4162c2d4b481e044ef2c642d917d368499e42dd6a72e93
-  data.tar.gz: 2f2d55a5ea98bc761ccabd6cce0e3e5ac417b0b5b659094c05ca74178abd77752e392c6b6104621ab750ba97aa1264f5b4d541e47c4a243e20b037b1417b69ab
+  metadata.gz: 4e374766292936272c50ca95fd2b63ae97f5cb044d194a879dc268009e453630406e090fb57227dcb3dc19f964a04ec3c12dd7b40500cbfd1f1f6b218771e7cc
+  data.tar.gz: c18398441c0d63526cb6fce609907eea627830a7dc71803688542a29950d8b0cf7ed1bd9d30dc3c0be3c154f53ba4f568707b855c3e01e001f5cdbc7ed9a1ff6

data/README.md

@@ -349,3 +349,22 @@ result.user_intent # => "Book my flights to the Austin offsite in October" or ni
 ```
 
 `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/tokens_client.rb

@@ -54,14 +54,21 @@ module AgentAdmit
     #   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, or if
-    #   user_intent is a non-String (other than nil) or 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,
-                    user_intent: 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
@@ -77,10 +84,18 @@ module AgentAdmit
       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.8.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.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 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