agentadmit 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74299884ea21ad2cb70261b0d2e7025bf4bc07e330f76bfc44009af8bba3b71b
-  data.tar.gz: 846ec2f9b8ed3afe7e9113fa7e1c1bf4b2fd7b074ce0f61e96550347db6c185b
+  metadata.gz: 885a1ed3458153db1420a5b58acf902aafecdea120ef3e51ce238c25e635562a
+  data.tar.gz: d0477df5f1302c204fb751a28343a8986ed964e18c814f5b72abfb274037a1e3
 SHA512:
-  metadata.gz: 25964578da91a2be9763398021fad033e9538cf6270c2fe99d66185c4da6d884514bcf9c9cfd9a2f60d017e0aeecdeb62d9d6ce1ef19ebfa543eb274cf2cc688
-  data.tar.gz: fdba91838161e85923cca0e4f1c84d72b724ad7bcf8e1be1c248f6af5ab1c1ec2506345e27016e7c8b3a7a989c5c65c3474fa263c23466cc7b100ec06b4263fc
+  metadata.gz: ad67e5e7b68872e5f9004e0da11b22d5ce7337f56725338fa9678e209e8689706f135fd0b4cd5eb042760944826757bcfc372f9dbbd223eb94a853e6692cbd75
+  data.tar.gz: 27780e1514e4296eba0aa2e345b888de8cbc74e44326ebbec4c3e0abd694c0026862387987b9264774bee8edffa125b44faf19b12e43d85cb36816bac7322c18

data/README.md

@@ -96,6 +96,43 @@ 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).
 
+**One-middleware drop-in.** Instead of wiring the three paths by hand, `AgentAdmit::CallerConsent` classifies the caller from the credential and evaluates the right independent path:
+
+```ruby
+use AgentAdmit::CallerConsent,
+    # derive the class from your own credential structure, never caller input
+    classify_non_agent: ->(env) {
+      env["HTTP_X_INTERNAL_AI"] == ENV["INTERNAL_AI_SECRET"] ? "in_app_ai" : "human_session"
+    },
+    resolve_data_owner_id: ->(env) { Rack::Request.new(env).params["owner_id"] },
+    required_scope: "read:records"
+# Downstream: env["agentadmit.caller_class"], env["agentadmit.consent"], and the
+# standard agent env variables on the external-agent path.
+```
+
+External agents are checked via hosted introspection (consent verdict plus scope); in-app AI via the Consent Ledger (fail closed); the human path defers to your own permission model unless `gate_human: true`. It is a consent gate, not an authenticator, so mount it after your own authentication.
+
+### 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/caller_consent.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module AgentAdmit
+  ##
+  # Caller-Identity Consent middleware: the "classify caller, then gate the
+  # right independent path" recipe as one Rack middleware, so an app owner
+  # does not have to hand-roll it.
+  #
+  # One endpoint serves every caller class. On each request the middleware:
+  #
+  #  1. classifies the caller from the STRUCTURE of the credential (a class
+  #     the caller cannot self-select), before any consent check;
+  #  2. routes to that class's ISOLATED consent path; no path reads or
+  #     inherits another class's preference;
+  #  3. permits or denies, and sets env variables
+  #     (agentadmit.caller_class, agentadmit.consent, plus the standard agent
+  #     env variables on the external-agent path).
+  #
+  #  - external_agent: an ag_at_ access token -> hosted introspection, which
+  #    returns the external-agent consent verdict inline plus the granted
+  #    scopes. Enforced here directly.
+  #  - in_app_ai: your application's own server-side AI code path -> the
+  #    Consent Ledger /consent/check for the in-app-AI class.
+  #  - human_session: your application's own permission model (sharing,
+  #    roles, grants). Deferred to your existing authorization by default;
+  #    opt in to a stored human-session switch with gate_human: true.
+  #
+  # The three decisions are independent: granting one never grants another.
+  #
+  # SECURITY: this is a consent gate, not an authenticator. It classifies the
+  # caller and enforces the per-class CONSENT decision; it does not by itself
+  # authenticate a human session. Mount it AFTER your own authentication. On
+  # the human_session path it defers to your application's permission model
+  # and calls the app without re-authenticating. The external_agent path is
+  # always authenticated (hosted introspection); the in_app_ai path always
+  # evaluates the ledger.
+  #
+  # Usage:
+  #   use AgentAdmit::CallerConsent,
+  #       # derive the class from your own credential structure, never caller input
+  #       classify_non_agent: ->(env) {
+  #         env["HTTP_X_INTERNAL_AI"] == ENV["INTERNAL_AI_SECRET"] ? "in_app_ai" : "human_session"
+  #       },
+  #       resolve_data_owner_id: ->(env) { Rack::Request.new(env).params["owner_id"] },
+  #       required_scope: "read:records"
+  #
+  class CallerConsent
+    # RFC 7235: the auth-scheme token is case-insensitive.
+    BEARER_AGENT_RE = /\Abearer ag_at_/i
+
+    HUMAN_SESSION  = "human_session"
+    IN_APP_AI      = "in_app_ai"
+    EXTERNAL_AGENT = "external_agent"
+
+    ##
+    # @param app [#call] the downstream Rack app
+    # @param resolve_data_owner_id [Proc, nil] env -> your app's identifier
+    #   for the data owner whose resource is accessed. Required for the
+    #   in_app_ai path, and for human_session when gate_human is set. The
+    #   external-agent owner comes from the token, so it is not used there.
+    # @param classify_non_agent [Proc, nil] env -> "in_app_ai" or
+    #   "human_session", derived from the STRUCTURE of the credential (for
+    #   example an internal service token), never a value the caller can set.
+    #   Defaults to treating non-agent callers as human sessions.
+    # @param required_scope [String, nil] for the external_agent path,
+    #   require this scope (403 insufficient_scope if not granted).
+    # @param scope_group [String, nil] optional finer-than-class consent
+    #   group for ledger checks.
+    # @param gate_human [Boolean] also gate the human_session class against a
+    #   stored switch. Off by default: the human path belongs to your own
+    #   permission model.
+    #
+    def initialize(app, resolve_data_owner_id: nil, classify_non_agent: nil,
+                   required_scope: nil, scope_group: nil, gate_human: false)
+      @app = app
+      @client = IntrospectionClient.new
+      @resolve_data_owner_id = resolve_data_owner_id
+      @classify_non_agent = classify_non_agent
+      @required_scope = required_scope
+      @scope_group = scope_group
+      @gate_human = gate_human
+    end
+
+    ##
+    # Classify the caller from credential structure, before any consent
+    # check. An ag_at_ bearer token is an external agent; anything else is
+    # resolved by classify_non_agent (default: human_session). The class is
+    # derived, never self-selected by the caller.
+    #
+    def classify_caller(env)
+      auth = env["HTTP_AUTHORIZATION"] || ""
+      return EXTERNAL_AGENT if BEARER_AGENT_RE.match?(auth)
+      return IN_APP_AI if @classify_non_agent && @classify_non_agent.call(env) == IN_APP_AI
+
+      HUMAN_SESSION
+    end
+
+    def call(env)
+      caller_class = classify_caller(env)
+      env["agentadmit.caller_class"] = caller_class
+
+      case caller_class
+      when EXTERNAL_AGENT
+        call_external_agent(env)
+      when IN_APP_AI
+        call_ledger_gated(env, IN_APP_AI, "in_app_ai",
+                          "The data owner has not enabled in-app AI analysis.")
+      else
+        if @gate_human
+          call_ledger_gated(env, HUMAN_SESSION, "user",
+                            "The data owner has not enabled this access.")
+        else
+          # Defer the human path to the app's existing authorization.
+          env["agentadmit.auth_type"] = "user"
+          @app.call(env)
+        end
+      end
+    end
+
+    private
+
+    ##
+    # External-agent path: hosted introspection carries the verdict and the
+    # scopes. A present-and-denied verdict fails closed; an absent verdict
+    # means the platform default (external-agent allowed) held.
+    #
+    def call_external_agent(env)
+      token = (env["HTTP_AUTHORIZATION"] || "").sub(/\Abearer /i, "")
+
+      begin
+        result = @client.verify(token)
+      rescue InvalidTokenError => e
+        return json_error(401, "invalid_token", e.message)
+      rescue IntrospectionError => e
+        return json_error(502, "introspection_failed", e.message)
+      end
+
+      if @required_scope && !(result.scopes || []).include?(@required_scope)
+        return [403, { "Content-Type" => "application/json" },
+                [{ error: "insufficient_scope",
+                   required_scope: @required_scope,
+                   granted_scopes: result.scopes || [],
+                   message: "This action requires '#{@required_scope}' scope." }.to_json]]
+      end
+
+      return json_error(403, "consent_not_granted",
+                        "The data owner has not enabled external agent access.") unless result.consent_granted?
+
+      env["agentadmit.auth_type"] = "agent"
+      env["agentadmit.user_id"] = result.user_id
+      env["agentadmit.scopes"] = result.scopes
+      env["agentadmit.connection_id"] = result.connection_id
+      env["agentadmit.agent_label"] = result.agent_label
+      env["agentadmit.presence"] = result.presence
+      env["agentadmit.consent"] = result.consent if result.consent
+
+      @app.call(env)
+    end
+
+    ##
+    # Token-less caller class (in_app_ai, or human_session under gate_human),
+    # gated on the Consent Ledger. Fail closed: an unreachable or erroring
+    # ledger denies, never allows.
+    #
+    def call_ledger_gated(env, caller_class, auth_type, denied_message)
+      owner = @resolve_data_owner_id&.call(env)
+      if owner.nil? || owner.empty?
+        return json_error(500, "server_error",
+                          "resolve_data_owner_id is required for this caller class")
+      end
+
+      begin
+        verdict = @client.check_consent(app_user_id: owner, caller_class: caller_class,
+                                        scope_group: @scope_group)
+      rescue StandardError
+        return json_error(503, "consent_unavailable", "Consent check failed")
+      end
+
+      return json_error(403, "consent_not_granted", denied_message) unless verdict["granted"] == true
+
+      env["agentadmit.auth_type"] = auth_type
+      env["agentadmit.consent"] = verdict
+      @app.call(env)
+    end
+
+    def json_error(status, error, description)
+      [status, { "Content-Type" => "application/json" },
+       [{ error: error, error_description: description }.to_json]]
+    end
+  end
+end

data/lib/agentadmit/introspection_client.rb

@@ -16,7 +16,8 @@ module AgentAdmit
     MAX_RETRY_BUDGET_MS = 120_000
 
     IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
-                                     :sub, :role, :app_id, :jti, :exp, :consent, keyword_init: true) do
+                                     :sub, :role, :app_id, :jti, :exp, :consent,
+                                     :presence, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -34,6 +35,16 @@ module AgentAdmit
         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)
@@ -157,6 +168,13 @@ module AgentAdmit
         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"],
@@ -167,7 +185,8 @@ module AgentAdmit
           app_id:       data["app_id"],
           jti:          data["jti"],
           exp:          data["exp"],
-          consent:      consent
+          consent:      consent,
+          presence:     presence
         )
       end
 

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.3.0"
+  VERSION = "1.5.0"
 end

data/lib/agentadmit.rb

@@ -92,6 +92,7 @@ require_relative "agentadmit/tokens_client"
 require_relative "agentadmit/alerts_client"
 require_relative "agentadmit/webhook"
 require_relative "agentadmit/middleware"
+require_relative "agentadmit/caller_consent"
 # ScopeEnforcement is an ActiveSupport::Concern — only loadable inside Rails.
 require_relative "agentadmit/scope_enforcement" if defined?(ActiveSupport)
 require_relative "agentadmit/railtie" if defined?(Rails)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentadmit
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-04 00:00:00.000000000 Z
+date: 2026-07-14 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/caller_consent.rb
 - lib/agentadmit/config.rb
 - lib/agentadmit/introspection_client.rb
 - lib/agentadmit/middleware.rb