agentadmit 1.1.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8231757da1987653f73ed2c9b1cfa48c8745c2220856d99da8427fc017406616
-  data.tar.gz: a0128eb51759e86da018e9852db33cafaf853b86fb9f7cd3f15f6aabd06009e6
+  metadata.gz: 74299884ea21ad2cb70261b0d2e7025bf4bc07e330f76bfc44009af8bba3b71b
+  data.tar.gz: 846ec2f9b8ed3afe7e9113fa7e1c1bf4b2fd7b074ce0f61e96550347db6c185b
 SHA512:
-  metadata.gz: 5eb0d7b249d27e9f5455eabc5b3214493dcd82b6be6563530ec05c66669aef52ae164aba352a21c744024be2b2b7a080fa5581bafff3ff9a1dc4aecab76f78a1
-  data.tar.gz: 8f955a6ac7d15948da7bf679e7fab80d5d0576110c672ba1e179f9e5458d6e1a6ef12dc60325d121dc41ccecdb69d0d709c3bbc8c125c3bff5bc6780c6601c84
+  metadata.gz: 25964578da91a2be9763398021fad033e9538cf6270c2fe99d66185c4da6d884514bcf9c9cfd9a2f60d017e0aeecdeb62d9d6ce1ef19ebfa543eb274cf2cc688
+  data.tar.gz: fdba91838161e85923cca0e4f1c84d72b724ad7bcf8e1be1c248f6af5ab1c1ec2506345e27016e7c8b3a7a989c5c65c3474fa263c23466cc7b100ec06b4263fc

data/README.md

@@ -2,7 +2,7 @@
 
 User-mediated AI agent authorization. Plug-and-play for any Rails app.
 
-> **Get started:** Sign up at [agentadmit.com](https://agentadmit.com) → Get your test keys → Install the SDK → Build.
+> **Get started:** Sign up at [agentadmit.com](https://agentadmit.com) -- Get your test keys -- Install the SDK -- Build.
 > Test keys are available immediately after signup. Live keys become available when you subscribe an app.
 
 ## Quick Start
@@ -14,7 +14,6 @@ gem 'agentadmit'
 
 ```bash
 bundle install
-rails generate agentadmit:install
 ```
 
 Add your credentials to `config/credentials.yml.enc` or `.env`:
@@ -24,6 +23,14 @@ AGENTADMIT_APP_ID=app_yourappid
 AGENTADMIT_API_KEY=aa_test_yourkey
 ```
 
+Create an initializer at `config/initializers/agentadmit.rb`:
+
+```ruby
+AgentAdmit.configure do |config|
+  # Defaults are read from ENV - nothing required here unless you need overrides.
+end
+```
+
 Add scope enforcement to any controller:
 
 ```ruby
@@ -36,13 +43,16 @@ class OrdersController < ApplicationController
 end
 ```
 
+The `require_scope_if_agent!` method is available in all controllers automatically
+when you use Rails -- the Railtie includes `AgentAdmit::ScopeEnforcement` into
+`ActionController::Base` on load.
+
 Your app now supports AI agent connections with:
 - Scoped access control (you define the scopes)
 - User-controlled connection duration
 - Token generation and exchange
 - Mandatory introspection (every agent request validated through AgentAdmit)
-- Revocation and audit logging
-- Discovery endpoint at `/.well-known/agentadmit`
+- Revocation support via `tokens.revoke`
 
 ## How It Works
 
@@ -58,27 +68,49 @@ The token goes to the human, not the agent. No automated delivery = no prompt in
 
 **Mandatory introspection.** All token validation goes through api.agentadmit.com. There is no self-hosted mode. No local JWT validation. No bypass. This is required for security, audit logging, and scope enforcement.
 
-**Admin revocation.** As the app operator, you can revoke any user's agent connection via `DELETE /agentadmit/admin/connections/{connection_id}` (requires admin role or `manage:connections` scope).
-
 **Embeddable admin panel.** Drop the `<AgentAdmitAdminPanel>` React component into your admin section to view all agent connections, usage metrics, billing status, and revoke any connection without leaving your app. See the React SDK for details.
 
 **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.
+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.
 
 ### Retry behavior
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | Initial delay | 1 second | First retry wait |
-| Backoff multiplier | 2× | Doubles each retry |
+| Backoff multiplier | 2x | Doubles each retry |
 | Cap | 30 seconds | Maximum wait per retry |
-| Jitter | 0–500 ms | Random addition to each delay |
+| Jitter | 0-500 ms | Random addition to each delay |
 | Max retries | **3** | Configurable |
 
-The SDK also respects the `Retry-After` response header — if present, it overrides the computed backoff delay.
+The SDK also respects the `Retry-After` response header -- if present, it overrides the computed backoff delay.
 
 ### Configuring max retries
 
@@ -107,10 +139,10 @@ end
 ```
 
 `RateLimitError` attributes:
-- `retry_after` — seconds from `Retry-After` header (`nil` if absent)
-- `limit` — `X-RateLimit-Limit` header value (`nil` if absent)
-- `remaining` — `X-RateLimit-Remaining` header value (`nil` if absent)
-- `reset` — `X-RateLimit-Reset` Unix timestamp (`nil` if absent)
+- `retry_after` -- seconds from `Retry-After` header (`nil` if absent)
+- `limit` -- `X-RateLimit-Limit` header value (`nil` if absent)
+- `remaining` -- `X-RateLimit-Remaining` header value (`nil` if absent)
+- `reset` -- `X-RateLimit-Reset` Unix timestamp (`nil` if absent)
 
 ## Documentation
 
@@ -122,14 +154,14 @@ Full integration guide: https://agentadmit.com/docs/app-owner-guide
 The AgentAdmit Ruby SDK runs server-side and does not interact with app stores or end-user devices directly.
 
 ### What the SDK does
-- Validates AgentAdmit tokens by calling AgentAdmit's hosted introspection endpoint (`https://api.agentadmit.com/api/v1/verify`) on every agent request — this is mandatory introspection; there is no local or offline validation mode
+- Validates AgentAdmit tokens by calling AgentAdmit's hosted introspection endpoint (`https://api.agentadmit.com/api/v1/verify`) on every agent request -- this is mandatory introspection; there is no local or offline validation mode
 - Enforces scope-based access control on your API routes
-- Manages connection lifecycle (create, revoke, audit) using your configured storage backend
+- Manages connection lifecycle (create, revoke) using the AgentAdmit hosted service
 
 ### What the SDK does NOT do
-- Does not transmit raw end-user PII (such as name, email, or device identifiers) — each introspection request sends the opaque access token and your API key
-- Does not perform passive background telemetry or analytics — network calls occur only during active token validation
-- Does not maintain its own persistent storage — local state (connections, audit log) lives in the storage backend you configure
+- Does not transmit raw end-user PII (such as name, email, or device identifiers) -- each introspection request sends the opaque access token and your API key
+- Does not perform passive background telemetry or analytics -- network calls occur only during active token validation
+- Does not maintain its own persistent local storage
 
 ### What the AgentAdmit hosted service records
 On every token validation, AgentAdmit's `/api/v1/verify` endpoint receives the access token and API key, resolves the token to its `user_id`, `connection_id`, granted `scopes`, and `agent_label`, and records per-call metadata (including the endpoint and timestamp) for billing, audit logging, the security alerts engine, and usage metering. This is integral to how AgentAdmit works and applies to both test and live keys. See the "Mandatory introspection" notes above and the [compliance guide](https://agentadmit.com/docs/compliance) for the full data-handling description.
@@ -177,10 +209,10 @@ config = alerts.get_alert_config(app_id: 'app_abc123')
 
 ### Notifying Your Users
 
-AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes connections. **How you notify your own users is up to you.** AgentAdmit provides the data — you deliver it through your own system (in-app notifications, email, push, etc.).
+AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes connections. **How you notify your own users is up to you.** AgentAdmit provides the data -- you deliver it through your own system (in-app notifications, email, push, etc.).
 
-- **Poll alerts** — Use the SDK methods above from your backend to check for new events, then notify users through your existing system.
-- **Webhook delivery** — Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit POSTs the payload to your server, signed with your `whsec_…` secret. Always verify the signature against the raw request body before trusting the payload:
+- **Poll alerts** -- Use the SDK methods above from your backend to check for new events, then notify users through your existing system.
+- **Webhook delivery** -- Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit POSTs the payload to your server, signed with your `whsec_...` secret. Always verify the signature against the raw request body before trusting the payload:
 
   ```ruby
   # Rails controller
@@ -188,7 +220,7 @@ AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes
     AgentAdmit::Webhook.verify_signature(
       request.raw_post,
       request.headers["X-AgentAdmit-Signature"].to_s,
-      AgentAdmit.configuration.webhook_secret # whsec_… from AGENTADMIT_WEBHOOK_SECRET
+      AgentAdmit.configuration.webhook_secret # whsec_... from AGENTADMIT_WEBHOOK_SECRET
     )
     event = JSON.parse(request.raw_post)
     # ...
@@ -198,8 +230,8 @@ AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes
   end
   ```
 
-  The header format is `t=<unix_ts>,v1=<hex>` — an HMAC-SHA256 of `{t}.{raw_body}` keyed with your signing secret. Verification compares in constant time and rejects timestamps more than 5 minutes off (replay protection).
-- **React SDK** — Embed the `<AlertsPanel>` component so users can view their own alert history and tighten thresholds.
+  The header format is `t=<unix_ts>,v1=<hex>` -- an HMAC-SHA256 of `{t}.{raw_body}` keyed with your signing secret. Verification compares in constant time and rejects timestamps more than 5 minutes off (replay protection).
+- **React SDK** -- Embed the `<AlertsPanel>` component so users can view their own alert history and tighten thresholds.
 
 ### Issuing & Exchanging Tokens
 
@@ -207,18 +239,18 @@ AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes
 tokens = AgentAdmit::TokensClient.new
 
 # Duration is tri-state:
-#   omit the argument          → AgentAdmit default (30 days)
-#   nil                        → until the user revokes
-#   Integer (60–31536000)      → explicit seconds
+#   omit the argument          => AgentAdmit default (30 days)
+#   nil                        => until the user revokes
+#   Integer (60-31536000)      => explicit seconds
 issued = tokens.issue_token(
   user_id: "user_42",
   scopes: ["read:orders"],
   role: "user",
   duration_seconds: nil # until revoked
 )
-connection_token = issued["token"] # ag_ct_…
+connection_token = issued["token"] # ag_ct_...
 
-# Agent side — no API key needed; the connection token is the credential.
+# Agent side -- no API key needed; the connection token is the credential.
 granted = tokens.exchange(connection_token, agent_label: "MyAssistant")
 
 # Revoke when the user disconnects the agent.

data/lib/agentadmit/config.rb

@@ -5,26 +5,39 @@
 # There is no self-hosted mode. No local JWT validation. No bypass.
 # This is required for security, audit logging, and scope enforcement.
 
+require "uri"
+
 module AgentAdmit
   class Config
-    attr_accessor :app_id, :api_key, :verify_url, :api_url,
-                  :token_prefix_access, :token_prefix_connection,
+    attr_accessor :app_id, :api_key, :token_prefix_access, :token_prefix_connection,
                   :webhook_secret, :max_retries
 
+    attr_reader :verify_url, :api_url
+
     def initialize
       @app_id = ENV.fetch("AGENTADMIT_APP_ID", "")
       @api_key = ENV.fetch("AGENTADMIT_API_KEY", "")
-      @verify_url = ENV.fetch("AGENTADMIT_VERIFY_URL", "https://api.agentadmit.com/api/v1/verify")
-      @api_url = ENV.fetch("AGENTADMIT_API_URL", "https://api.agentadmit.com")
+      self.verify_url = ENV.fetch("AGENTADMIT_VERIFY_URL", "https://api.agentadmit.com/api/v1/verify")
+      self.api_url    = ENV.fetch("AGENTADMIT_API_URL", "https://api.agentadmit.com")
       @token_prefix_access = "ag_at_"
       @token_prefix_connection = "ag_ct_"
-      # Webhook signing secret (whsec_…) — shown once when you configure the
+      # Webhook signing secret (whsec_...) -- shown once when you configure the
       # alert webhook URL in the dashboard. Used by AgentAdmit::Webhook.
       @webhook_secret = ENV.fetch("AGENTADMIT_WEBHOOK_SECRET", "")
       # Max retries on HTTP 429 before raising RateLimitError. Default: 3.
       @max_retries = ENV.fetch("AGENTADMIT_MAX_RETRIES", "3").to_i
     end
 
+    def verify_url=(url)
+      validate_url!(url, :verify_url)
+      @verify_url = url
+    end
+
+    def api_url=(url)
+      validate_url!(url, :api_url)
+      @api_url = url
+    end
+
     ##
     # Validate the API key prefix (aa_test_/aa_live_) without ever echoing
     # the key itself.
@@ -37,5 +50,30 @@ module AgentAdmit
 
       raise ConfigurationError, "api_key must start with 'aa_test_' or 'aa_live_'"
     end
+
+    private
+
+    # Local loopback hostnames / addresses that are allowed over plain HTTP.
+    LOCALHOST_HOSTS = %w[localhost 127.0.0.1 [::1]].freeze
+
+    ##
+    # Raise ConfigurationError for non-https URLs unless the host is localhost.
+    #
+    def validate_url!(url, field)
+      return if url.nil? || url.empty?
+
+      uri = URI.parse(url)
+      return if uri.scheme == "https"
+
+      if uri.scheme == "http" && LOCALHOST_HOSTS.include?(uri.host)
+        return
+      end
+
+      raise ConfigurationError,
+        "#{field} must use https (got: #{url.inspect}). " \
+        "Plain http is only permitted for localhost / 127.0.0.1 / [::1]."
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "#{field} is not a valid URL: #{url.inspect}"
+    end
   end
 end

data/lib/agentadmit/introspection_client.rb

@@ -6,15 +6,34 @@ require "uri"
 
 module AgentAdmit
   ##
-  # Mandatory introspection client — validates tokens via AgentAdmit hosted service.
+  # Mandatory introspection client -- validates tokens via AgentAdmit hosted service.
   # No local JWT decode. Every verification call goes through AgentAdmit.
   #
   class IntrospectionClient
+    # Hard cap on any single retry wait -- including a server-supplied Retry-After.
+    MAX_RETRY_WAIT_MS = 30_000
+    # Hard cap on cumulative wait across all retries of a single verify call.
+    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)
@@ -41,6 +60,7 @@ module AgentAdmit
 
       max_retries = @config.respond_to?(:max_retries) ? @config.max_retries.to_i : 3
       delay_ms    = 1000 # initial backoff in milliseconds
+      waited_ms   = 0    # cumulative wait across retries
 
       uri  = URI.parse(@config.verify_url)
       http = build_http(uri)
@@ -72,11 +92,25 @@ module AgentAdmit
             )
           end
 
-          # Compute wait: honor Retry-After header or use exponential backoff, cap at 30s
-          wait_ms   = retry_after ? (retry_after * 1000).ceil : [delay_ms, 30_000].min
+          # Compute wait: Retry-After beats exponential backoff, but both are
+          # capped -- Retry-After is untrusted server input and must not pin
+          # the caller.
+          requested_ms = retry_after ? (retry_after * 1000).ceil : delay_ms
+          wait_ms   = [[requested_ms, 0].max, MAX_RETRY_WAIT_MS].min
           jitter_ms = rand(0..500)
           total_ms  = wait_ms + jitter_ms
 
+          if waited_ms + total_ms > MAX_RETRY_BUDGET_MS
+            raise RateLimitError.new(
+              "AgentAdmit rate limit retry budget (#{MAX_RETRY_BUDGET_MS / 1000}s) exhausted.",
+              retry_after: retry_after,
+              limit: rl_limit,
+              remaining: rl_remaining,
+              reset: rl_reset
+            )
+          end
+          waited_ms += total_ms
+
           warn "[AgentAdmit] Rate-limited (attempt #{attempt + 1}/#{max_retries}). " \
                "Retrying in #{total_ms}ms."
 
@@ -85,54 +119,143 @@ module AgentAdmit
           next
         end
 
-        # Non-429 response — process normally
-        case status
-        when 200
-          data = JSON.parse(response.body)
-
-          # Check active flag (RFC 7662 introspection pattern).
-          # The verify endpoint returns {active: false} with HTTP 200 for
-          # invalid/expired/revoked tokens; the error code is one of
-          # VERIFY_ERROR_CODES (e.g. token_expired, connection_expired,
-          # environment_mismatch). Without this check, we'd read empty scopes.
-          unless data["active"]
-            reason = data["error"] || "invalid_token"
-            raise InvalidTokenError.new("Token is not active: #{reason}", code: reason)
+        # Non-429: only treat 2xx as a candidate for a valid token.
+        unless (200..299).cover?(status)
+          if status == 401
+            data = JSON.parse(response.body) rescue {}
+            raise InvalidTokenError, data["error_description"] || "Token validation failed"
           end
+          raise IntrospectionError, "Verification service returned #{response.code}"
+        end
 
-          # insufficient_scope arrives with active: true (token valid,
-          # requested scope not granted).
-          if data["error"] == "insufficient_scope"
-            raise InsufficientScopeError, data["error_description"] || "Scope not granted"
-          end
+        # 2xx -- parse and strictly validate the response body.
+        data = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise IntrospectionError, "Introspection response is not valid JSON"
+        end
 
-          raise InvalidTokenError, "Introspection returned no user" if data["user_id"].nil?
-
-          return IntrospectionResult.new(
-            user_id:      data["user_id"],
-            connection_id: data["connection_id"],
-            scopes:       data["scopes"] || [],
-            agent_label:  data["agent_label"] || "Unknown Agent",
-            sub:          data["sub"],
-            role:         data["role"],
-            app_id:       data["app_id"],
-            jti:          data["jti"],
-            exp:          data["exp"]
-          )
-        when 401
-          data = JSON.parse(response.body) rescue {}
-          raise InvalidTokenError, data["error_description"] || "Token validation failed"
-        else
-          raise IntrospectionError, "Verification service returned #{response.code}"
+        # active must be strictly true (boolean).
+        unless data["active"] == true
+          reason = data["error"] || "invalid_token"
+          raise InvalidTokenError.new("Token is not active: #{reason}", code: reason)
         end
+
+        # insufficient_scope arrives with active: true (token valid,
+        # requested scope not granted).
+        if data["error"] == "insufficient_scope"
+          raise InsufficientScopeError, data["error_description"] || "Scope not granted"
+        end
+
+        # 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"],
+          scopes:       data["scopes"] || [],
+          agent_label:  data["agent_label"] || "Unknown Agent",
+          sub:          data["sub"],
+          role:         data["role"],
+          app_id:       data["app_id"],
+          jti:          data["jti"],
+          exp:          data["exp"],
+          consent:      consent
+        )
       end
 
       # Should never be reached
       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
 
+    ##
+    # Enforce that the fields the middleware relies on have the correct types.
+    # Any type mismatch means we cannot safely use the response -- treat as invalid.
+    #
+    # @raise [InvalidTokenError]
+    #
+    def validate_introspection_types!(data)
+      # user_id is required and must be a String.
+      unless data["user_id"].is_a?(String)
+        raise InvalidTokenError, "Introspection returned no user"
+      end
+
+      # agent_id, connection_id -- must be String when present.
+      %w[agent_id connection_id].each do |field|
+        val = data[field]
+        next if val.nil?
+        unless val.is_a?(String)
+          raise InvalidTokenError, "Introspection field '#{field}' must be a String"
+        end
+      end
+
+      # scopes -- must be Array of Strings when present.
+      if data.key?("scopes")
+        scopes = data["scopes"]
+        unless scopes.is_a?(Array) && scopes.all? { |s| s.is_a?(String) }
+          raise InvalidTokenError, "Introspection field 'scopes' must be an Array of Strings"
+        end
+      end
+    end
+
     def build_http(uri)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl     = uri.scheme == "https"

data/lib/agentadmit/middleware.rb

@@ -6,13 +6,17 @@ module AgentAdmit
   # and validates them via introspection.
   #
   # Sets env variables for downstream use:
-  #   env['agentadmit.auth_type']     — "agent" or nil
-  #   env['agentadmit.user_id']       — validated user ID
-  #   env['agentadmit.scopes']        — granted scopes array
-  #   env['agentadmit.connection_id'] — connection identifier
-  #   env['agentadmit.agent_label']   — agent display name
+  #   env['agentadmit.auth_type']     -- "agent" or nil
+  #   env['agentadmit.user_id']       -- validated user ID
+  #   env['agentadmit.scopes']        -- granted scopes array
+  #   env['agentadmit.connection_id'] -- connection identifier
+  #   env['agentadmit.agent_label']   -- agent display name
   #
   class Middleware
+    # RFC 7235: the auth-scheme token is case-insensitive.
+    # Match "bearer", "Bearer", "BEARER", etc. followed by the ag_at_ prefix.
+    BEARER_AGENT_RE = /\Abearer ag_at_/i
+
     def initialize(app)
       @app = app
       @client = IntrospectionClient.new
@@ -22,8 +26,9 @@ module AgentAdmit
     def call(env)
       auth = env["HTTP_AUTHORIZATION"] || ""
 
-      if auth.start_with?("Bearer #{@config.token_prefix_access}")
-        token = auth.sub("Bearer ", "")
+      if BEARER_AGENT_RE.match?(auth)
+        # Strip the scheme prefix (case-insensitively) to get the bare token.
+        token = auth.sub(/\Abearer /i, "")
 
         begin
           result = @client.verify(token)

data/lib/agentadmit/railtie.rb

@@ -4,6 +4,7 @@ module AgentAdmit
   class Railtie < Rails::Railtie
     initializer "agentadmit.middleware" do |app|
       app.middleware.use AgentAdmit::Middleware
+      Rails.logger.info "[AgentAdmit] Middleware and scope enforcement active."
     end
 
     initializer "agentadmit.configure" do
@@ -11,5 +12,12 @@ module AgentAdmit
         # Config loaded from environment variables by default
       end
     end
+
+    # Include ScopeEnforcement into every ActionController so that
+    # require_scope_if_agent! and require_scope! are available without
+    # an explicit `include` in each controller.
+    ActiveSupport.on_load(:action_controller) do
+      include AgentAdmit::ScopeEnforcement
+    end
   end
 end

data/lib/agentadmit/version.rb

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

metadata

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