agentadmit 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f416bd1136c1ff49766c515270c9c8ef4102a2474960923af9648d49406e64
-  data.tar.gz: 2b86e062d60f5c3c762f0845ba1a13b8c60e394ad9b7db1b0fd296d804ac7087
+  metadata.gz: bc3085f5469fd5380afb22df98cf1517e1f74df3a23cf7ab07d7f6c490cd9feb
+  data.tar.gz: fb0142a79357486644fff3e68903194b998cf5b41c1f140a8bda8f7a2f0c2909
 SHA512:
-  metadata.gz: 4e48106a82e8b4bfe8d89828972347b5a33afbfb60908cae5b1b3e9d92887c52f8d118d4817dc8d880dcae51a41d9cf88f3d92f53557fb4d4ae619c1186eeeb7
-  data.tar.gz: 7f370525b8e98ff57a5849d083a2e5a6ddc8af4edcdfe229dbe7499db9188d922fc9f60bfe0d441d7b6dbe8b1320048fbf743c91a9b5de64401733b9ae4c9c3f
+  metadata.gz: e54b1b2f7c357b546388d09a9accf94c29c98964ade0d5888e87962d3d30219486cf30b932234d503e46d6ea80e4a6348a165a6172a09b4d182390709c605713
+  data.tar.gz: 3d237b464785de4d0a8a081d992dd7313c77c84a3bdac92f0a3a9dc41a2909137cfec0415d7eb67dd4408c1eb772d24ff514e996184ad0d580b9f047fcd0a59d

data/README.md

@@ -72,6 +72,51 @@ The token goes to the human, not the agent. No automated delivery = no prompt in
 
 **In-app AI scopes.** If your app has built-in AI features (analysis, plan generation, photo recognition), do not expose those as agent scopes. The user's AI agent can read the raw data and do the analysis itself. Exposing in-app AI endpoints to agents creates double cost.
 
+### Consent Ledger (Caller-Identity Consent)
+
+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:
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(token)
+unless result.consent_granted?
+  # the data owner has switched external agents off: return your own 403
+end
+```
+
+**Human sessions and in-app AI** never hold AgentAdmit tokens, so ask directly:
+
+```ruby
+verdict = AgentAdmit::IntrospectionClient.new.check_consent(
+  app_user_id: "user_8842", caller_class: "in_app_ai"
+)
+head :forbidden unless verdict["granted"]
+```
+
+Consent is orthogonal to revocation: a denied verdict means your app returns its own 403; the connection and token stay valid so the user can flip consent back on without re-connecting. Write switches through `PUT /api/v1/consent/settings` from your backend; export the audit trail with `GET /api/v1/consent/export` (every plan).
+
+### Presence verification
+
+AgentAdmit can attest that the human who authorized a connection completed a WebAuthn presence ceremony on the consent page. The verify result carries the fact:
+
+```ruby
+result = AgentAdmit::IntrospectionClient.new.verify(token)
+result.presence_verified?  # true only when the ceremony completed
+```
+
+For sensitive actions, enforce it in your controllers the same way you enforce scopes:
+
+```ruby
+class TransfersController < ApplicationController
+  include AgentAdmit::ScopeEnforcement
+
+  before_action -> { require_presence! }, only: [:create]
+end
+```
+
+`require_presence!` fails closed: agents whose connection was minted without a completed ceremony get a 403 `presence_required`, and so do connections from servers that predate the feature. `presence_verified?` returns true only on an explicit boolean `verified: true`; absent or malformed presence data reads as not verified.
+
 ## Rate Limiting
 
 The AgentAdmit introspection endpoint enforces rate limits. The Ruby SDK handles HTTP 429 responses **automatically** with exponential backoff and jitter -- no changes needed in your middleware code.

data/lib/agentadmit/introspection_client.rb

@@ -16,10 +16,35 @@ module AgentAdmit
     MAX_RETRY_BUDGET_MS = 120_000
 
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
-                                     :sub, :role, :app_id, :jti, :exp, keyword_init: true) do
+                                     :sub, :role, :app_id, :jti, :exp, :consent,
+                                     :presence, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
+
+      # Consent Ledger verdict for the external-agent path (additive; may be
+      # 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).
+      def consent_granted?
+        return true if consent.nil?
+        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.
+      def presence_verified?
+        presence.is_a?(Hash) && presence["verified"] == true
+      end
     end
 
     def initialize(config = nil)
@@ -136,6 +161,20 @@ 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.
+        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.
+        presence = data["presence"]
+        presence = nil unless presence.is_a?(Hash) && [true, false].include?(presence["verified"])
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -145,7 +184,9 @@ module AgentAdmit
           role:         data["role"],
           app_id:       data["app_id"],
           jti:          data["jti"],
-          exp:          data["exp"]
+          exp:          data["exp"],
+          consent:      consent,
+          presence:     presence
         )
       end
 
@@ -153,6 +194,55 @@ module AgentAdmit
       raise IntrospectionError, "Unexpected exit from retry loop"
     end
 
+    CALLER_CLASSES = %w[human_session in_app_ai external_agent].freeze
+
+    ##
+    # Ask the Consent Ledger whether a caller class may act on a user's data.
+    # Decision point for the token-less caller classes (human_session,
+    # in_app_ai); external agents get the same verdict on the verify result.
+    #
+    # @param app_user_id [String] your app's identifier for the data owner
+    # @param caller_class [String] "human_session" | "in_app_ai" | "external_agent"
+    # @param scope_group [String, nil] optional finer-than-class group
+    # @return [Hash] verdict: granted, caller_class, scope_group, source, evaluated_at
+    # @raise [ArgumentError] unknown caller_class
+    # @raise [IntrospectionError] hosted service unreachable or rejected the call
+    #
+    def check_consent(app_user_id:, caller_class:, scope_group: nil)
+      unless CALLER_CLASSES.include?(caller_class)
+        raise ArgumentError, "caller_class must be one of #{CALLER_CLASSES.join(', ')}"
+      end
+
+      uri  = URI.parse("#{@config.api_url.sub(%r{/\z}, '')}/api/v1/consent/check")
+      http = build_http(uri)
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Authorization"] = "Bearer #{@config.api_key}"
+      request["Content-Type"]  = "application/json"
+      body = { app_user_id: app_user_id, caller_class: caller_class }
+      body[:scope_group] = scope_group if scope_group
+      request.body = JSON.generate(body)
+
+      response = begin
+        http.request(request)
+      rescue StandardError => e
+        raise IntrospectionError, "Consent check failed: #{e.message}"
+      end
+
+      unless (200..299).cover?(response.code.to_i)
+        data = JSON.parse(response.body) rescue {}
+        raise IntrospectionError,
+              data["error_description"] || data["error"] || "Consent check returned #{response.code}"
+      end
+
+      # 2xx -- parse strictly; a garbage body must not read as an empty verdict.
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise IntrospectionError, "Consent check response is not valid JSON"
+      end
+    end
+
     private
 
     ##

data/lib/agentadmit/middleware.rb

@@ -11,6 +11,7 @@ module AgentAdmit
   #   env['agentadmit.scopes']        -- granted scopes array
   #   env['agentadmit.connection_id'] -- connection identifier
   #   env['agentadmit.agent_label']   -- agent display name
+  #   env['agentadmit.presence']      -- human-presence block (Hash) or nil
   #
   class Middleware
     # RFC 7235: the auth-scheme token is case-insensitive.
@@ -37,6 +38,7 @@ module AgentAdmit
           env["agentadmit.scopes"] = result.scopes
           env["agentadmit.connection_id"] = result.connection_id
           env["agentadmit.agent_label"] = result.agent_label
+          env["agentadmit.presence"] = result.presence
         rescue InvalidTokenError => e
           return [401, { "Content-Type" => "application/json" },
             [{ error: "invalid_token", error_description: e.message }.to_json]]

data/lib/agentadmit/scope_enforcement.rb

@@ -10,6 +10,7 @@ module AgentAdmit
   #
   #     before_action -> { require_scope!("read:orders") }, only: [:index, :show]
   #     before_action -> { require_scope_if_agent!("create:orders") }, only: [:create]
+  #     before_action -> { require_presence! }, only: [:destroy]
   #   end
   #
   module ScopeEnforcement
@@ -54,6 +55,27 @@ module AgentAdmit
       end
     end
 
+    ##
+    # Enforce human-presence verification -- agent's connection MUST have been
+    # authorized with a completed WebAuthn presence ceremony or gets 403.
+    # Fail closed: connections from servers that predate the presence feature
+    # (no presence block) are treated as not verified.
+    #
+    def require_presence!
+      unless request.env["agentadmit.auth_type"] == "agent"
+        render json: { error: "invalid_token", error_description: "AgentAdmit token required" }, status: :unauthorized
+        return
+      end
+
+      presence = request.env["agentadmit.presence"]
+      unless presence.is_a?(Hash) && presence["verified"] == true
+        render json: {
+          error: "presence_required",
+          error_description: "This action requires a connection authorized with human presence verification."
+        }, status: :forbidden
+      end
+    end
+
     ##
     # Get the current agent/user context.
     #
@@ -64,6 +86,7 @@ module AgentAdmit
         scopes: request.env["agentadmit.scopes"],
         connection_id: request.env["agentadmit.connection_id"],
         agent_label: request.env["agentadmit.agent_label"],
+        presence: request.env["agentadmit.presence"],
       }
     end
   end

data/lib/agentadmit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

metadata

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