agentadmit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71a63361a9ebd638c907411b5dcbce487f000d940c2618887d68ffe90a9bc5fa
-  data.tar.gz: c48534a09f1d07e05d56b34c88dfe2ecc64fcdc61564e880f2c1e948e18c9e67
+  metadata.gz: f9dee1c87344bc7be4a6ae662446c18c5ac25fe40dbe384091524026127c091a
+  data.tar.gz: 477af00d19a84da65d0405f804982272bceceec85661e7f9a4afba8332c408f3
 SHA512:
-  metadata.gz: fc1d745572d89c57767e20bb6320d47816580d8d7a1a07d75333564d2b32ed562843a467483799f793d81b12d5ed185915d8afd376a206ee82029cebd5eb7d9c
-  data.tar.gz: 8f1f126ad0d27e99fac5e3e58fb43a6064a3078bae8b0b921ce8b3a8499caeaa16a249d7142180c84a76b8d26bc76cfcafaf073965b1e5f3591a83d4493b0889
+  metadata.gz: 97aef14949cfaea7090597db980330fc7cc7bfadf63909cdaced2d4e6c9889d0492f03108a0f6db4a31f42243e0dea8eb04c921a3058e6c4c37cab56ecade685
+  data.tar.gz: 30b10080024db2dc44b238bf2afa0941b15f697d465c58ed966208a1afbf9d9294fd212f5fe353c832f4ea0bc3491e16e0f63c37089fd3da961aa7d54cb5efaf

data/README.md

@@ -140,3 +140,85 @@ For complete compliance guidance, see our [compliance guide](https://agentadmit.
 ## License
 
 All rights reserved. Patent pending.
+
+## Security Alerts
+
+```ruby
+alerts = AgentAdmit::AlertsClient.new
+```
+
+Six alert type constants: `ALERT_TYPE_VOLUME_SPIKE`, `ALERT_TYPE_FAILED_SCOPE_ATTEMPTS`, `ALERT_TYPE_BURST_PATTERN`, `ALERT_TYPE_STALE_REACTIVATION`, `ALERT_TYPE_NEW_SCOPE_USAGE`, `ALERT_TYPE_REVOKED_CONNECTION_ATTEMPT`.
+
+### Configure
+
+```ruby
+alerts.configure_alerts(
+  app_id: 'app_abc123',
+  alert_type: AgentAdmit::AlertsClient::ALERT_TYPE_VOLUME_SPIKE,
+  enabled: true, threshold_value: 100, threshold_window_minutes: 5,
+  kill_switch_enabled: true,
+)
+```
+
+### List Events
+
+```ruby
+result = alerts.list_alerts(app_id: 'app_abc123', alert_type: AgentAdmit::AlertsClient::ALERT_TYPE_VOLUME_SPIKE)
+```
+
+### Get Config
+
+```ruby
+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.).
+
+- **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
+  def alerts
+    AgentAdmit::Webhook.verify_signature(
+      request.raw_post,
+      request.headers["X-AgentAdmit-Signature"].to_s,
+      AgentAdmit.configuration.webhook_secret # whsec_… from AGENTADMIT_WEBHOOK_SECRET
+    )
+    event = JSON.parse(request.raw_post)
+    # ...
+    head :ok
+  rescue AgentAdmit::WebhookSignatureError
+    head :bad_request
+  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.
+
+### Issuing & Exchanging Tokens
+
+```ruby
+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
+issued = tokens.issue_token(
+  user_id: "user_42",
+  scopes: ["read:orders"],
+  role: "user",
+  duration_seconds: nil # until revoked
+)
+connection_token = issued["token"] # ag_ct_…
+
+# 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.
+tokens.revoke(granted["connection_id"], reason: "user_requested")
+```

data/lib/agentadmit/alerts_client.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module AgentAdmit
+  ##
+  # AlertsClient — configure and query security alerts via the AgentAdmit hosted service.
+  #
+  # Supported alert types:
+  #   ALERT_TYPE_VOLUME_SPIKE, ALERT_TYPE_FAILED_SCOPE_ATTEMPTS,
+  #   ALERT_TYPE_BURST_PATTERN, ALERT_TYPE_STALE_REACTIVATION,
+  #   ALERT_TYPE_NEW_SCOPE_USAGE, ALERT_TYPE_REVOKED_CONNECTION_ATTEMPT
+  #
+  # @example
+  #   client = AgentAdmit::AlertsClient.new
+  #
+  #   client.configure_alerts(
+  #     app_id:                   "app_abc123",
+  #     alert_type:               AgentAdmit::AlertsClient::ALERT_TYPE_VOLUME_SPIKE,
+  #     enabled:                  true,
+  #     threshold_value:          100,
+  #     threshold_window_minutes: 5,
+  #   )
+  #
+  class AlertsClient
+    ALERT_TYPE_VOLUME_SPIKE               = "volume_spike"
+    ALERT_TYPE_FAILED_SCOPE_ATTEMPTS      = "failed_scope_attempts"
+    ALERT_TYPE_BURST_PATTERN              = "burst_pattern"
+    ALERT_TYPE_STALE_REACTIVATION         = "stale_reactivation"
+    ALERT_TYPE_NEW_SCOPE_USAGE            = "new_scope_usage"
+    ALERT_TYPE_REVOKED_CONNECTION_ATTEMPT = "revoked_connection_attempt"
+
+    def initialize(config = nil)
+      @config = config || AgentAdmit.configuration || Config.new
+    end
+
+    ##
+    # Configure alert thresholds for an app or connection.
+    # POST /api/v1/alerts
+    #
+    # @param app_id [String]
+    # @param alert_type [String] One of the ALERT_TYPE_* constants
+    # @param connection_id [String, nil]
+    # @param enabled [Boolean, nil]
+    # @param threshold_value [Numeric, nil]
+    # @param threshold_window_minutes [Integer, nil]
+    # @param threshold_rate_per_minute [Numeric, nil]
+    # @param stale_days [Integer, nil]
+    # @param kill_switch_enabled [Boolean, nil]
+    # @param kill_switch_threshold_value [Numeric, nil]
+    # @param kill_switch_threshold_window_minutes [Integer, nil]
+    # @return [Hash] { "ok" => true, "config" => {...} }
+    # @raise [IntrospectionError]
+    #
+    def configure_alerts(
+      app_id:,
+      alert_type:,
+      connection_id: nil,
+      enabled: nil,
+      threshold_value: nil,
+      threshold_window_minutes: nil,
+      threshold_rate_per_minute: nil,
+      stale_days: nil,
+      kill_switch_enabled: nil,
+      kill_switch_threshold_value: nil,
+      kill_switch_threshold_window_minutes: nil
+    )
+      body = { app_id: app_id, alert_type: alert_type }
+      body[:connection_id]                        = connection_id                        unless connection_id.nil?
+      body[:enabled]                              = enabled                              unless enabled.nil?
+      body[:threshold_value]                      = threshold_value                      unless threshold_value.nil?
+      body[:threshold_window_minutes]             = threshold_window_minutes             unless threshold_window_minutes.nil?
+      body[:threshold_rate_per_minute]            = threshold_rate_per_minute            unless threshold_rate_per_minute.nil?
+      body[:stale_days]                           = stale_days                           unless stale_days.nil?
+      body[:kill_switch_enabled]                  = kill_switch_enabled                  unless kill_switch_enabled.nil?
+      body[:kill_switch_threshold_value]          = kill_switch_threshold_value          unless kill_switch_threshold_value.nil?
+      body[:kill_switch_threshold_window_minutes] = kill_switch_threshold_window_minutes unless kill_switch_threshold_window_minutes.nil?
+
+      post_json("/api/v1/alerts", body)
+    end
+
+    ##
+    # List alert events for an app.
+    # GET /api/v1/alerts
+    #
+    # @param app_id [String]
+    # @param connection_id [String, nil]
+    # @param alert_type [String, nil]
+    # @param limit [Integer] default 50
+    # @param offset [Integer] default 0
+    # @return [Hash] { "events" => [...], "total" => Integer, "limit" => Integer, "offset" => Integer }
+    # @raise [IntrospectionError]
+    #
+    def list_alerts(app_id:, connection_id: nil, alert_type: nil, limit: 50, offset: 0)
+      params = { app_id: app_id, limit: limit, offset: offset }
+      params[:connection_id] = connection_id if connection_id
+      params[:alert_type]    = alert_type    if alert_type
+
+      get_json("/api/v1/alerts", params)
+    end
+
+    ##
+    # Get the current alert configuration for an app.
+    # GET /api/v1/alerts/config
+    #
+    # @param app_id [String]
+    # @param connection_id [String, nil]
+    # @return [Hash] { "app_id", "app_level", "connection_overrides", "alert_types" }
+    # @raise [IntrospectionError]
+    #
+    def get_alert_config(app_id:, connection_id: nil)
+      params = { app_id: app_id }
+      params[:connection_id] = connection_id if connection_id
+
+      get_json("/api/v1/alerts/config", params)
+    end
+
+    private
+
+    def api_base
+      base = @config.respond_to?(:api_url) ? @config.api_url : "https://api.agentadmit.com"
+      base.to_s.chomp("/")
+    end
+
+    def auth_headers
+      {
+        "Authorization" => "Bearer #{@config.api_key}",
+        "X-App-Id"      => @config.app_id.to_s,
+        "Content-Type"  => "application/json",
+      }
+    end
+
+    def post_json(path, body)
+      uri  = URI.parse("#{api_base}#{path}")
+      http = build_http(uri)
+      req  = Net::HTTP::Post.new(uri.path)
+      auth_headers.each { |k, v| req[k] = v }
+      req.body = JSON.generate(body)
+
+      response = http.request(req)
+      check_status(response, "POST #{path}")
+      JSON.parse(response.body)
+    rescue IntrospectionError
+      raise
+    rescue StandardError => e
+      raise IntrospectionError, "AgentAdmit alerts request failed: #{e.message}"
+    end
+
+    def get_json(path, params = {})
+      query = URI.encode_www_form(params)
+      uri   = URI.parse("#{api_base}#{path}?#{query}")
+      http  = build_http(uri)
+      req   = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
+      auth_headers.each { |k, v| req[k] = v }
+
+      response = http.request(req)
+      check_status(response, "GET #{path}")
+      JSON.parse(response.body)
+    rescue IntrospectionError
+      raise
+    rescue StandardError => e
+      raise IntrospectionError, "AgentAdmit alerts request failed: #{e.message}"
+    end
+
+    def build_http(uri)
+      http              = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.read_timeout = 10
+      http.open_timeout = 5
+      http
+    end
+
+    def check_status(response, operation)
+      status = response.code.to_i
+      return if status < 400
+
+      raise IntrospectionError,
+        "AgentAdmit #{operation} failed with HTTP #{status}: #{response.body}"
+    end
+  end
+end

data/lib/agentadmit/config.rb

@@ -9,17 +9,33 @@ module AgentAdmit
   class Config
     attr_accessor :app_id, :api_key, :verify_url, :api_url,
                   :token_prefix_access, :token_prefix_connection,
-                  :max_retries
+                  :webhook_secret, :max_retries
 
     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/v1/verify")
+      @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")
       @token_prefix_access = "ag_at_"
       @token_prefix_connection = "ag_ct_"
+      # 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
+
+    ##
+    # Validate the API key prefix (aa_test_/aa_live_) without ever echoing
+    # the key itself.
+    #
+    # @raise [ConfigurationError] if a non-empty key has the wrong prefix
+    #
+    def validate_api_key!
+      return if api_key.nil? || api_key.empty?
+      return if api_key.start_with?("aa_test_", "aa_live_")
+
+      raise ConfigurationError, "api_key must start with 'aa_test_' or 'aa_live_'"
+    end
   end
 end

data/lib/agentadmit/introspection_client.rb

@@ -10,7 +10,8 @@ module AgentAdmit
   # No local JWT decode. Every verification call goes through AgentAdmit.
   #
   class IntrospectionClient
-    IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label, keyword_init: true) do
+    IntrospectionResult = Struct.new(:user_id, :connection_id, :scopes, :agent_label,
+                                     :sub, :role, :app_id, :jti, :exp, keyword_init: true) do
       def has_scope?(scope)
         scopes.include?(scope)
       end
@@ -18,6 +19,7 @@ module AgentAdmit
 
     def initialize(config = nil)
       @config = config || AgentAdmit.configuration || Config.new
+      @config.validate_api_key!
     end
 
     ##
@@ -89,11 +91,19 @@ module AgentAdmit
           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. Without this check, we'd read empty scopes.
+          # 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, "Token is not active: #{reason}"
+            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
 
           raise InvalidTokenError, "Introspection returned no user" if data["user_id"].nil?
@@ -102,7 +112,12 @@ module AgentAdmit
             user_id:      data["user_id"],
             connection_id: data["connection_id"],
             scopes:       data["scopes"] || [],
-            agent_label:  data["agent_label"] || "Unknown Agent"
+            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 {}

data/lib/agentadmit/tokens_client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module AgentAdmit
+  ##
+  # TokensClient — issue, exchange, and revoke connection tokens via the
+  # AgentAdmit hosted service.
+  #
+  class TokensClient
+    # Sentinel for issue_token's duration_seconds: leave the field out of the
+    # request entirely, so AgentAdmit applies its default (30 days). Pass nil
+    # instead for an until-revoked connection (explicit JSON null).
+    UNSET = Object.new.freeze
+
+    def initialize(config = nil)
+      @config = config || AgentAdmit.configuration || Config.new
+      @config.validate_api_key!
+    end
+
+    ##
+    # Issue a connection token for one of your users.
+    # Calls POST /api/v1/apps/{app_id}/token.
+    #
+    # The duration is tri-state:
+    # - omit the argument — field omitted; AgentAdmit applies its default
+    #   (30 days)
+    # - nil — explicit JSON null; the connection lasts until revoked
+    # - Integer — explicit duration in seconds (60–31536000)
+    #
+    # @param user_id [String] your app's identifier for the user
+    # @param scopes [Array<String>] scopes the connection grants
+    # @param role [String, nil] the user's role on the connection
+    # @param duration_seconds [Integer, nil, UNSET] see above
+    # @return [Hash] the issue response — "token" is the self-describing
+    #   ag_ct_… connection token to hand to the user's agent
+    # @raise [IntrospectionError] if issuance fails
+    #
+    def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET)
+      body = { "user_id" => user_id, "scopes" => scopes }
+      body["role"] = role if role
+      # Tri-state: the UNSET sentinel omits the key entirely; nil survives
+      # JSON.generate as explicit JSON null (no compact, no nil-guard).
+      body["duration_seconds"] = duration_seconds unless duration_seconds.equal?(UNSET)
+
+      post("/api/v1/apps/#{@config.app_id}/token", body, authenticated: true, op: "issue_token")
+    end
+
+    ##
+    # Exchange a single-use connection token for an access token.
+    # Calls POST /api/v1/exchange — unauthenticated by design: the connection
+    # token itself is the credential, so the operator API key is NOT sent.
+    #
+    # @param connection_token [String] the ag_ct_… connection token
+    # @param agent_label [String, nil] human-readable agent name
+    # @param agent_id [String, nil] agent identifier
+    # @return [Hash] the exchange response — "access_token" is the ag_at_… token
+    # @raise [IntrospectionError] if the exchange fails
+    #
+    def exchange(connection_token, agent_label: nil, agent_id: nil)
+      body = { "token" => connection_token }
+      body["agent_label"] = agent_label if agent_label
+      body["agent_id"] = agent_id if agent_id
+
+      post("/api/v1/exchange", body, authenticated: false, op: "exchange")
+    end
+
+    ##
+    # Revoke a connection (and its access tokens).
+    # Calls POST /api/v1/revoke.
+    #
+    # @param connection_id [String] the connection to revoke
+    # @param reason [String, nil] optional human-readable reason
+    # @return [Hash] the revoke response — { "ok" => true, ... }
+    # @raise [IntrospectionError] if the revocation fails
+    #
+    def revoke(connection_id, reason: nil)
+      body = { "connection_id" => connection_id }
+      body["reason"] = reason if reason
+
+      post("/api/v1/revoke", body, authenticated: true, op: "revoke")
+    end
+
+    private
+
+    def post(path, body, authenticated:, op:)
+      uri = URI.parse("#{@config.api_url.chomp('/')}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 10
+      http.open_timeout = 10
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      if authenticated
+        # No Authorization on /exchange — the connection token is the credential.
+        request["Authorization"] = "Bearer #{@config.api_key}"
+        request["X-App-Id"] = @config.app_id
+      end
+      request.body = JSON.generate(body)
+
+      begin
+        response = http.request(request)
+      rescue StandardError => e
+        raise IntrospectionError, "#{op} failed: #{e.message}"
+      end
+
+      status = response.code.to_i
+      raise IntrospectionError, "#{op} returned #{status}" if status >= 400
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise IntrospectionError, "#{op} returned an unparseable response"
+    end
+  end
+end

data/lib/agentadmit/version.rb

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

data/lib/agentadmit/webhook.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module AgentAdmit
+  ##
+  # Verification for inbound AgentAdmit alert webhooks.
+  #
+  # AgentAdmit signs every alert webhook delivery with the app's webhook
+  # signing secret (whsec_…, returned once when the webhook URL is
+  # configured). The signature arrives in the X-AgentAdmit-Signature header:
+  #
+  #   X-AgentAdmit-Signature: t=<unix_ts>,v1=<hex hmac-sha256>
+  #
+  # where the HMAC input is "{t}.{raw_body}" keyed with the full whsec_
+  # secret. Always verify against the raw request body (request.raw_post in
+  # Rails), before any JSON parsing.
+  #
+  # @example Rails controller
+  #   def alerts
+  #     AgentAdmit::Webhook.verify_signature(
+  #       request.raw_post,
+  #       request.headers["X-AgentAdmit-Signature"].to_s,
+  #       AgentAdmit.configuration.webhook_secret
+  #     )
+  #     event = JSON.parse(request.raw_post)
+  #     # ...
+  #   rescue AgentAdmit::WebhookSignatureError
+  #     head :bad_request
+  #   end
+  #
+  module Webhook
+    # Header AgentAdmit signs alert webhook deliveries with.
+    SIGNATURE_HEADER = "X-AgentAdmit-Signature"
+
+    # Default maximum clock skew (seconds) allowed for replay protection.
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    module_function
+
+    ##
+    # Verify the X-AgentAdmit-Signature header on an inbound alert webhook.
+    #
+    # @param payload [String] the raw request body
+    # @param header [String] the X-AgentAdmit-Signature header value
+    # @param secret [String] the app's webhook signing secret (whsec_…)
+    # @param tolerance [Integer] max clock skew in seconds (0 disables the check)
+    # @param now [Integer, nil] override the current Unix timestamp (for tests)
+    # @raise [WebhookSignatureError] if the header is missing/malformed, the
+    #   timestamp is outside the tolerance window, or no signature matches;
+    #   the message never includes the secret or the payload
+    # @return [void]
+    #
+    def verify_signature(payload, header, secret, tolerance: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      raise WebhookSignatureError, "Webhook signing secret is required" if secret.nil? || secret.empty?
+      raise WebhookSignatureError, "Missing X-AgentAdmit-Signature header" if header.nil? || header.empty?
+
+      timestamp = nil
+      candidates = []
+      header.split(",").each do |part|
+        key, _, value = part.strip.partition("=")
+        case key
+        when "t"
+          raise WebhookSignatureError, "Malformed signature header" unless value.match?(/\A\d+\z/)
+
+          timestamp = Integer(value)
+        when "v1"
+          candidates << value
+        end
+      end
+
+      raise WebhookSignatureError, "Malformed signature header" if timestamp.nil? || candidates.empty?
+
+      if tolerance.positive? && ((now || Time.now.to_i) - timestamp).abs > tolerance
+        raise WebhookSignatureError, "Signature timestamp outside tolerance window"
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+      matched = candidates.any? { |candidate| secure_compare(expected, candidate) }
+
+      raise WebhookSignatureError, "Webhook signature verification failed" unless matched
+    end
+
+    ##
+    # Boolean form of {verify_signature}.
+    #
+    # @return [Boolean]
+    #
+    def valid_signature?(payload, header, secret, tolerance: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      verify_signature(payload, header, secret, tolerance: tolerance, now: now)
+      true
+    rescue WebhookSignatureError
+      false
+    end
+
+    ##
+    # Constant-time string comparison (portable — OpenSSL.secure_compare is
+    # not available on every openssl gem version).
+    #
+    # @api private
+    #
+    def secure_compare(expected, candidate)
+      return false unless expected.bytesize == candidate.bytesize
+
+      diff = 0
+      expected_bytes = expected.unpack("C*")
+      candidate.each_byte.with_index { |byte, i| diff |= byte ^ expected_bytes[i] }
+      diff.zero?
+    end
+  end
+end

data/lib/agentadmit.rb

@@ -1,17 +1,49 @@
 # frozen_string_literal: true
 
 require_relative "agentadmit/version"
-require_relative "agentadmit/config"
-require_relative "agentadmit/introspection_client"
-require_relative "agentadmit/middleware"
-require_relative "agentadmit/scope_enforcement"
-require_relative "agentadmit/railtie" if defined?(Rails)
 
 module AgentAdmit
   class Error < StandardError; end
-  class InvalidTokenError < Error; end
+
+  ##
+  # Raised when token validation fails. {#code} carries the machine-readable
+  # reason from the API — one of VERIFY_ERROR_CODES (e.g. token_expired,
+  # connection_expired, environment_mismatch); unknown codes pass through.
+  #
+  class InvalidTokenError < Error
+    # @return [String] machine-readable error code
+    attr_reader :code
+
+    def initialize(message = "Invalid access token", code: "invalid_token")
+      super(message)
+      @code = code
+    end
+  end
+
   class InsufficientScopeError < Error; end
   class IntrospectionError < Error; end
+  class ConfigurationError < Error; end
+
+  ##
+  # Raised when an inbound alert webhook fails X-AgentAdmit-Signature
+  # verification.
+  #
+  class WebhookSignatureError < Error; end
+
+  ##
+  # Error codes /api/v1/verify returns with HTTP 200 and active: false
+  # (insufficient_scope arrives with active: true — token valid, scope not
+  # granted).
+  #
+  VERIFY_ERROR_CODES = %w[
+    invalid_token
+    token_expired
+    token_revoked
+    connection_revoked
+    connection_expired
+    environment_mismatch
+    insufficient_scope
+  ].freeze
 
   ##
   # Raised when the AgentAdmit introspection endpoint returns HTTP 429 and
@@ -53,3 +85,13 @@ module AgentAdmit
     end
   end
 end
+
+require_relative "agentadmit/config"
+require_relative "agentadmit/introspection_client"
+require_relative "agentadmit/tokens_client"
+require_relative "agentadmit/alerts_client"
+require_relative "agentadmit/webhook"
+require_relative "agentadmit/middleware"
+# 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.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Christopher Emerson
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -26,7 +26,7 @@ dependencies:
         version: '0'
 description: Integrate AgentAdmit into your Rails app. Mandatory introspection, scope
   enforcement, and secure AI agent connections.
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -34,17 +34,20 @@ files:
 - LICENSE
 - README.md
 - lib/agentadmit.rb
+- lib/agentadmit/alerts_client.rb
 - lib/agentadmit/config.rb
 - lib/agentadmit/introspection_client.rb
 - lib/agentadmit/middleware.rb
 - lib/agentadmit/railtie.rb
 - lib/agentadmit/scope_enforcement.rb
+- lib/agentadmit/tokens_client.rb
 - lib/agentadmit/version.rb
+- lib/agentadmit/webhook.rb
 homepage: https://agentadmit.com/docs
 licenses:
 - Nonstandard
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -59,8 +62,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: AgentAdmit SDK for Ruby on Rails — User-mediated AI agent authorization
 test_files: []