agentadmit 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3085f5469fd5380afb22df98cf1517e1f74df3a23cf7ab07d7f6c490cd9feb
-  data.tar.gz: fb0142a79357486644fff3e68903194b998cf5b41c1f140a8bda8f7a2f0c2909
+  metadata.gz: 810b958cd0fd3558a19bfc79910e194e45e02d95331b98747ff4edf29e337d8a
+  data.tar.gz: 4c18ad2b306eea918107543eeee24c3f2eb7f30010bfb3c1bb6502bcfa94718b
 SHA512:
-  metadata.gz: e54b1b2f7c357b546388d09a9accf94c29c98964ade0d5888e87962d3d30219486cf30b932234d503e46d6ea80e4a6348a165a6172a09b4d182390709c605713
-  data.tar.gz: 3d237b464785de4d0a8a081d992dd7313c77c84a3bdac92f0a3a9dc41a2909137cfec0415d7eb67dd4408c1eb772d24ff514e996184ad0d580b9f047fcd0a59d
+  metadata.gz: 4a0a65b2ce47a30683c14de7c397bea637adbe18ed76db7b8b579c5835d5dcdb90881ef93e20c687710cc37184ec3fc796a9fd153e1f6bf19edcb8f1c2875463
+  data.tar.gz: b81a5431a0a2b37728e675963ab79e188e5d0e288f4bb2a4e8497fe5df81ba7a962fc15d99b36fd21d72fa6472de266bb2dacef92aab79f46c04b615bcd31e58

data/README.md

@@ -76,15 +76,24 @@ The token goes to the human, not the agent. No automated delivery = no prompt in
 
 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:
+**External agents:** the verify result already carries the verdict. The hosted service deliberately omits the verdict when its consent store is unreadable (degraded mode), so an absent verdict is *unresolved*, never a grant — `consent_granted?` fails closed on it. Resolve an absent or malformed verdict through the ledger:
 
 ```ruby
-result = AgentAdmit::IntrospectionClient.new.verify(token)
-unless result.consent_granted?
+client = AgentAdmit::IntrospectionClient.new
+result = client.verify(token)
+consent = result.consent
+unless consent.is_a?(Hash) && [true, false].include?(consent["granted"])
+  # absent/malformed verdict: the ledger holds the authoritative answer
+  consent = client.check_consent(app_user_id: result.user_id,
+                                 caller_class: "external_agent") # fail closed on error
+end
+unless consent["granted"] == true
   # the data owner has switched external agents off: return your own 403
 end
 ```
 
+The `AgentAdmit::CallerConsent` middleware does all of this for you: it evaluates the consent verdict **before** the scope check (a caller whose class the owner denied learns nothing about scope state) and resolves an absent verdict through the Consent Ledger, fail-closed.
+
 **Human sessions and in-app AI** never hold AgentAdmit tokens, so ask directly:
 
 ```ruby
@@ -96,6 +105,22 @@ 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:

data/lib/agentadmit/caller_consent.rb

@@ -0,0 +1,215 @@
+# 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. Consent is evaluated BEFORE scope (a denied class must not
+  #    learn scope state). A missing or malformed verdict is resolved through
+  #    the Consent Ledger, fail-closed -- absence is never a grant.
+  #  - 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. Consent is evaluated first (Patent FIG. 3: the class consent
+    # decision precedes scope evaluation) -- checking scope first would leak
+    # granted-scope state to callers whose class the owner has denied. The
+    # hosted service omits the verdict when its consent-store read fails
+    # (designed degraded mode), so an absent or malformed verdict is resolved
+    # through the Consent Ledger, fail-closed -- never treated as a grant.
+    #
+    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
+
+      consent = result.consent
+      unless consent.is_a?(Hash) && [true, false].include?(consent["granted"])
+        owner = result.user_id
+        if !owner.is_a?(String) || owner.empty?
+          return json_error(503, "consent_unavailable",
+                            "Introspection carried no consent verdict and no resolvable data owner")
+        end
+
+        begin
+          consent = @client.check_consent(app_user_id: owner, caller_class: EXTERNAL_AGENT,
+                                          scope_group: @scope_group)
+        rescue StandardError
+          return json_error(503, "consent_unavailable", "Consent check failed")
+        end
+      end
+
+      unless consent.is_a?(Hash) && consent["granted"] == true
+        return json_error(403, "consent_not_granted",
+                          "The data owner has not enabled external agent access.")
+      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
+
+      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"] = 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

@@ -26,22 +26,24 @@ module AgentAdmit
       # 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).
+      # Contract: grants ONLY on an explicit boolean true. An ABSENT block is
+      # NEVER a grant -- the hosted service deliberately omits it when its
+      # consent-store read fails (designed degraded mode), so absence here
+      # fails closed. A missing or non-boolean granted value is likewise
+      # denied (malformed = deny). Callers that want the authoritative answer
+      # for an absent/malformed verdict should resolve it through
+      # #check_consent for the external_agent class (CallerConsent does this
+      # automatically).
       def consent_granted?
-        return true if consent.nil?
-        consent["granted"] == true
+        consent.is_a?(Hash) && 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.
+      # true. 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
@@ -161,17 +163,17 @@ 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.
+        # Keep the consent block only when it is a Hash; anything else reads
+        # as nil. Absent and malformed are both safe: neither is ever a grant
+        # (consent_granted? fails closed, and CallerConsent resolves the
+        # authoritative verdict through the Consent Ledger).
         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.
+        # 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"])
 

data/lib/agentadmit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentAdmit
-  VERSION = "1.4.0"
+  VERSION = "1.5.1"
 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.4.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Christopher Emerson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-07-17 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