agentadmit 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f416bd1136c1ff49766c515270c9c8ef4102a2474960923af9648d49406e64
-  data.tar.gz: 2b86e062d60f5c3c762f0845ba1a13b8c60e394ad9b7db1b0fd296d804ac7087
+  metadata.gz: 74299884ea21ad2cb70261b0d2e7025bf4bc07e330f76bfc44009af8bba3b71b
+  data.tar.gz: 846ec2f9b8ed3afe7e9113fa7e1c1bf4b2fd7b074ce0f61e96550347db6c185b
 SHA512:
-  metadata.gz: 4e48106a82e8b4bfe8d89828972347b5a33afbfb60908cae5b1b3e9d92887c52f8d118d4817dc8d880dcae51a41d9cf88f3d92f53557fb4d4ae619c1186eeeb7
-  data.tar.gz: 7f370525b8e98ff57a5849d083a2e5a6ddc8af4edcdfe229dbe7499db9188d922fc9f60bfe0d441d7b6dbe8b1320048fbf743c91a9b5de64401733b9ae4c9c3f
+  metadata.gz: 25964578da91a2be9763398021fad033e9538cf6270c2fe99d66185c4da6d884514bcf9c9cfd9a2f60d017e0aeecdeb62d9d6ce1ef19ebfa543eb274cf2cc688
+  data.tar.gz: fdba91838161e85923cca0e4f1c84d72b724ad7bcf8e1be1c248f6af5ab1c1ec2506345e27016e7c8b3a7a989c5c65c3474fa263c23466cc7b100ec06b4263fc

data/README.md

@@ -72,6 +72,30 @@ 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).
+
 ## 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,24 @@ 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, 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
     end
 
     def initialize(config = nil)
@@ -136,6 +150,13 @@ 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)
+
         return IntrospectionResult.new(
           user_id:      data["user_id"],
           connection_id: data["connection_id"],
@@ -145,7 +166,8 @@ module AgentAdmit
           role:         data["role"],
           app_id:       data["app_id"],
           jti:          data["jti"],
-          exp:          data["exp"]
+          exp:          data["exp"],
+          consent:      consent
         )
       end
 
@@ -153,6 +175,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/version.rb

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

metadata

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