agentadmit 1.0.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71a63361a9ebd638c907411b5dcbce487f000d940c2618887d68ffe90a9bc5fa
-  data.tar.gz: c48534a09f1d07e05d56b34c88dfe2ecc64fcdc61564e880f2c1e948e18c9e67
+  metadata.gz: 8231757da1987653f73ed2c9b1cfa48c8745c2220856d99da8427fc017406616
+  data.tar.gz: a0128eb51759e86da018e9852db33cafaf853b86fb9f7cd3f15f6aabd06009e6
 SHA512:
-  metadata.gz: fc1d745572d89c57767e20bb6320d47816580d8d7a1a07d75333564d2b32ed562843a467483799f793d81b12d5ed185915d8afd376a206ee82029cebd5eb7d9c
-  data.tar.gz: 8f1f126ad0d27e99fac5e3e58fb43a6064a3078bae8b0b921ce8b3a8499caeaa16a249d7142180c84a76b8d26bc76cfcafaf073965b1e5f3591a83d4493b0889
+  metadata.gz: 5eb0d7b249d27e9f5455eabc5b3214493dcd82b6be6563530ec05c66669aef52ae164aba352a21c744024be2b2b7a080fa5581bafff3ff9a1dc4aecab76f78a1
+  data.tar.gz: 8f955a6ac7d15948da7bf679e7fab80d5d0576110c672ba1e179f9e5458d6e1a6ef12dc60325d121dc41ccecdb69d0d709c3bbc8c125c3bff5bc6780c6601c84

data/README.md

@@ -122,15 +122,17 @@ 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 presented by AI agents
+- 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)
+- Manages connection lifecycle (create, revoke, audit) using your configured storage backend
 
 ### What the SDK does NOT do
-- Does not collect end-user data
-- Does not send telemetry or analytics
-- Does not phone home to AgentAdmit servers (all operations use your configured keys and storage)
-- Does not track users or devices
+- 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
+
+### 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.
 
 ### Privacy impact
 Since this SDK runs on your server, it has no direct App Store or Play Store compliance surface. Your client-side integration (e.g., the AgentAdmit React SDK) handles privacy manifest and data safety requirements.
@@ -140,3 +142,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.2"
 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.2
 platform: ruby
 authors:
 - Christopher Emerson
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-17 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: []