agentadmit 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71a63361a9ebd638c907411b5dcbce487f000d940c2618887d68ffe90a9bc5fa
+  data.tar.gz: c48534a09f1d07e05d56b34c88dfe2ecc64fcdc61564e880f2c1e948e18c9e67
+SHA512:
+  metadata.gz: fc1d745572d89c57767e20bb6320d47816580d8d7a1a07d75333564d2b32ed562843a467483799f793d81b12d5ed185915d8afd376a206ee82029cebd5eb7d9c
+  data.tar.gz: 8f1f126ad0d27e99fac5e3e58fb43a6064a3078bae8b0b921ce8b3a8499caeaa16a249d7142180c84a76b8d26bc76cfcafaf073965b1e5f3591a83d4493b0889

data/LICENSE

@@ -0,0 +1,56 @@
+AgentAdmit Proprietary License
+
+Copyright (c) 2026 AgentAdmit LLC. All rights reserved.
+
+Patent Pending — U.S. Application No. 19/660,916
+
+TERMS OF USE
+
+1. GRANT OF LICENSE. AgentAdmit LLC ("Licensor") grants you a limited,
+   non-exclusive, non-transferable, revocable license to use this software
+   development kit ("SDK") solely for the purpose of integrating with the
+   AgentAdmit hosted service (api.agentadmit.com).
+
+2. RESTRICTIONS. You may not:
+   (a) Use this SDK with any service other than the AgentAdmit hosted service;
+   (b) Modify, adapt, or create derivative works of this SDK for the purpose
+       of building or operating a competing service;
+   (c) Reverse engineer, decompile, or disassemble the AgentAdmit protocol
+       or service architecture;
+   (d) Remove or alter any proprietary notices, labels, or marks;
+   (e) Redistribute this SDK as a standalone product or as part of a
+       competing authorization service.
+
+3. PERMITTED USES. You may:
+   (a) Install and use this SDK in your applications;
+   (b) Include this SDK as a dependency in your projects;
+   (c) Distribute your applications that incorporate this SDK, provided
+       those applications connect to the AgentAdmit hosted service.
+
+4. AGENTADMIT SERVICE REQUIRED. This SDK is designed exclusively for use
+   with the AgentAdmit hosted service. An AgentAdmit account and valid API
+   keys are required. Sign up at https://agentadmit.com.
+
+5. INTELLECTUAL PROPERTY. The AgentAdmit protocol, user-mediated token
+   delivery mechanism, mandatory introspection architecture, and related
+   inventions are protected by pending U.S. patent(s) and other intellectual
+   property rights. This license does not grant any rights to the underlying
+   patents or trade secrets.
+
+6. NO WARRANTY. THIS SDK IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+7. LIMITATION OF LIABILITY. IN NO EVENT SHALL AGENTADMIT LLC BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING FROM YOUR USE OF THIS SDK.
+
+8. TERMINATION. This license terminates automatically if you violate any
+   of its terms. Upon termination, you must cease all use and destroy all
+   copies of this SDK in your possession.
+
+9. GOVERNING LAW. This license is governed by the laws of the State of
+   California, United States.
+
+For licensing inquiries: legal@agentadmit.com
+For developer support: https://agentadmit.com/docs

data/README.md

@@ -0,0 +1,142 @@
+# AgentAdmit SDK for Ruby (Rails)
+
+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.
+> Test keys are available immediately after signup. Live keys become available when you subscribe an app.
+
+## Quick Start
+
+```ruby
+# Gemfile
+gem 'agentadmit'
+```
+
+```bash
+bundle install
+rails generate agentadmit:install
+```
+
+Add your credentials to `config/credentials.yml.enc` or `.env`:
+
+```env
+AGENTADMIT_APP_ID=app_yourappid
+AGENTADMIT_API_KEY=aa_test_yourkey
+```
+
+Add scope enforcement to any controller:
+
+```ruby
+class OrdersController < ApplicationController
+  before_action -> { require_scope_if_agent!('read:orders') }
+
+  def index
+    render json: current_user.orders
+  end
+end
+```
+
+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`
+
+## How It Works
+
+1. User clicks "AgentAdmit" in your app
+2. Selects scopes and connection duration
+3. Gets a token to give to their AI agent
+4. Agent exchanges the token for scoped API access
+5. User revokes anytime
+
+The token goes to the human, not the agent. No automated delivery = no prompt injection surface.
+
+## Important
+
+**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.
+
+## 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.
+
+### Retry behavior
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Initial delay | 1 second | First retry wait |
+| Backoff multiplier | 2× | Doubles each retry |
+| Cap | 30 seconds | Maximum wait per retry |
+| 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.
+
+### Configuring max retries
+
+```ruby
+AgentAdmit.configure do |config|
+  config.max_retries = 5  # default: 3
+end
+```
+
+Or via environment variable:
+
+```env
+AGENTADMIT_MAX_RETRIES=5
+```
+
+### Handling exhausted retries
+
+When all retries are exhausted, `IntrospectionClient#verify` raises `AgentAdmit::RateLimitError`:
+
+```ruby
+begin
+  result = client.verify(token)
+rescue AgentAdmit::RateLimitError => e
+  render json: { error: 'rate_limited', retry_after: e.retry_after }, status: 429
+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)
+
+## Documentation
+
+Full integration guide: https://agentadmit.com/docs/app-owner-guide
+
+
+## Data Collection & Privacy
+
+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
+- Enforces scope-based access control on your API routes
+- Manages connection lifecycle (create, revoke, audit)
+
+### 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
+
+### 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.
+
+For complete compliance guidance, see our [compliance guide](https://agentadmit.com/docs/compliance).
+
+## License
+
+All rights reserved. Patent pending.

data/lib/agentadmit/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# IMPORTANT: AgentAdmit uses MANDATORY hosted 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.
+
+module AgentAdmit
+  class Config
+    attr_accessor :app_id, :api_key, :verify_url, :api_url,
+                  :token_prefix_access, :token_prefix_connection,
+                  :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")
+      @api_url = ENV.fetch("AGENTADMIT_API_URL", "https://api.agentadmit.com")
+      @token_prefix_access = "ag_at_"
+      @token_prefix_connection = "ag_ct_"
+      # Max retries on HTTP 429 before raising RateLimitError. Default: 3.
+      @max_retries = ENV.fetch("AGENTADMIT_MAX_RETRIES", "3").to_i
+    end
+  end
+end

data/lib/agentadmit/introspection_client.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module AgentAdmit
+  ##
+  # Mandatory introspection client — validates tokens via AgentAdmit hosted service.
+  # 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
+      def has_scope?(scope)
+        scopes.include?(scope)
+      end
+    end
+
+    def initialize(config = nil)
+      @config = config || AgentAdmit.configuration || Config.new
+    end
+
+    ##
+    # Validate an ag_at_ token via introspection.
+    #
+    # Automatically retries on HTTP 429 with exponential backoff + jitter.
+    # Raises {RateLimitError} when retries are exhausted.
+    #
+    # @param token [String] The full token including ag_at_ prefix
+    # @return [IntrospectionResult]
+    # @raise [InvalidTokenError] if validation fails
+    # @raise [IntrospectionError] if the service is unreachable
+    # @raise [RateLimitError] if rate-limited and retries exhausted
+    #
+    def verify(token)
+      unless token.start_with?(@config.token_prefix_access)
+        raise InvalidTokenError, "Not an AgentAdmit access token"
+      end
+
+      max_retries = @config.respond_to?(:max_retries) ? @config.max_retries.to_i : 3
+      delay_ms    = 1000 # initial backoff in milliseconds
+
+      uri  = URI.parse(@config.verify_url)
+      http = build_http(uri)
+
+      (0..max_retries).each do |attempt|
+        request = build_request(uri, token)
+
+        begin
+          response = http.request(request)
+        rescue StandardError => e
+          raise IntrospectionError, "Introspection failed: #{e.message}"
+        end
+
+        status = response.code.to_i
+
+        if status == 429
+          retry_after  = parse_float_header(response, "Retry-After")
+          rl_limit     = parse_int_header(response, "X-RateLimit-Limit")
+          rl_remaining = parse_int_header(response, "X-RateLimit-Remaining")
+          rl_reset     = parse_int_header(response, "X-RateLimit-Reset")
+
+          if attempt >= max_retries
+            raise RateLimitError.new(
+              "AgentAdmit rate limit exceeded. Max retries (#{max_retries}) exhausted.",
+              retry_after: retry_after,
+              limit: rl_limit,
+              remaining: rl_remaining,
+              reset: rl_reset
+            )
+          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
+          jitter_ms = rand(0..500)
+          total_ms  = wait_ms + jitter_ms
+
+          warn "[AgentAdmit] Rate-limited (attempt #{attempt + 1}/#{max_retries}). " \
+               "Retrying in #{total_ms}ms."
+
+          sleep(total_ms / 1000.0)
+          delay_ms = [delay_ms * 2, 30_000].min
+          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. Without this check, we'd read empty scopes.
+          unless data["active"]
+            reason = data["error"] || "invalid_token"
+            raise InvalidTokenError, "Token is not active: #{reason}"
+          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"
+          )
+        when 401
+          data = JSON.parse(response.body) rescue {}
+          raise InvalidTokenError, data["error_description"] || "Token validation failed"
+        else
+          raise IntrospectionError, "Verification service returned #{response.code}"
+        end
+      end
+
+      # Should never be reached
+      raise IntrospectionError, "Unexpected exit from retry loop"
+    end
+
+    private
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = uri.scheme == "https"
+      http.read_timeout = 5
+      http.open_timeout = 5
+      http
+    end
+
+    def build_request(uri, token)
+      req = Net::HTTP::Post.new(uri.path)
+      req["Authorization"] = "Bearer #{@config.api_key}"
+      req["Content-Type"]  = "application/json"
+      req.body = JSON.generate({ token: token })
+      req
+    end
+
+    ##
+    # Parse a response header as Float, returning nil if absent or non-numeric.
+    #
+    def parse_float_header(response, name)
+      val = response[name]
+      return nil if val.nil? || val.empty?
+      Float(val) rescue nil
+    end
+
+    ##
+    # Parse a response header as Integer, returning nil if absent or non-numeric.
+    #
+    def parse_int_header(response, name)
+      val = response[name]
+      return nil if val.nil? || val.empty?
+      Integer(val) rescue nil
+    end
+  end
+end

data/lib/agentadmit/middleware.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AgentAdmit
+  ##
+  # Rack middleware that intercepts requests with ag_at_ tokens
+  # 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
+  #
+  class Middleware
+    def initialize(app)
+      @app = app
+      @client = IntrospectionClient.new
+      @config = AgentAdmit.configuration || Config.new
+    end
+
+    def call(env)
+      auth = env["HTTP_AUTHORIZATION"] || ""
+
+      if auth.start_with?("Bearer #{@config.token_prefix_access}")
+        token = auth.sub("Bearer ", "")
+
+        begin
+          result = @client.verify(token)
+          env["agentadmit.auth_type"] = "agent"
+          env["agentadmit.user_id"] = result.user_id
+          env["agentadmit.scopes"] = result.scopes
+          env["agentadmit.connection_id"] = result.connection_id
+          env["agentadmit.agent_label"] = result.agent_label
+        rescue InvalidTokenError => e
+          return [401, { "Content-Type" => "application/json" },
+            [{ error: "invalid_token", error_description: e.message }.to_json]]
+        rescue IntrospectionError => e
+          return [502, { "Content-Type" => "application/json" },
+            [{ error: "introspection_failed", error_description: e.message }.to_json]]
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/agentadmit/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AgentAdmit
+  class Railtie < Rails::Railtie
+    initializer "agentadmit.middleware" do |app|
+      app.middleware.use AgentAdmit::Middleware
+    end
+
+    initializer "agentadmit.configure" do
+      AgentAdmit.configure do |config|
+        # Config loaded from environment variables by default
+      end
+    end
+  end
+end

data/lib/agentadmit/scope_enforcement.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AgentAdmit
+  ##
+  # Controller concern for scope enforcement in Rails controllers.
+  #
+  # Usage:
+  #   class OrdersController < ApplicationController
+  #     include AgentAdmit::ScopeEnforcement
+  #
+  #     before_action -> { require_scope!("read:orders") }, only: [:index, :show]
+  #     before_action -> { require_scope_if_agent!("create:orders") }, only: [:create]
+  #   end
+  #
+  module ScopeEnforcement
+    extend ActiveSupport::Concern
+
+    private
+
+    ##
+    # Enforce scope — agent MUST have this scope or gets 403.
+    #
+    def require_scope!(scope)
+      unless request.env["agentadmit.auth_type"] == "agent"
+        render json: { error: "invalid_token", error_description: "AgentAdmit token required" }, status: :unauthorized
+        return
+      end
+
+      scopes = request.env["agentadmit.scopes"] || []
+      unless scopes.include?(scope)
+        render json: {
+          error: "insufficient_scope",
+          required_scope: scope,
+          granted_scopes: scopes,
+          message: "This action requires '#{scope}' scope."
+        }, status: :forbidden
+      end
+    end
+
+    ##
+    # Enforce scope only for agent tokens. Regular users pass through.
+    #
+    def require_scope_if_agent!(scope)
+      return unless request.env["agentadmit.auth_type"] == "agent"
+
+      scopes = request.env["agentadmit.scopes"] || []
+      unless scopes.include?(scope)
+        render json: {
+          error: "insufficient_scope",
+          required_scope: scope,
+          granted_scopes: scopes,
+          message: "This action requires '#{scope}' scope."
+        }, status: :forbidden
+      end
+    end
+
+    ##
+    # Get the current agent/user context.
+    #
+    def agentadmit_context
+      {
+        auth_type: request.env["agentadmit.auth_type"],
+        user_id: request.env["agentadmit.user_id"],
+        scopes: request.env["agentadmit.scopes"],
+        connection_id: request.env["agentadmit.connection_id"],
+        agent_label: request.env["agentadmit.agent_label"],
+      }
+    end
+  end
+end

data/lib/agentadmit/version.rb

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

data/lib/agentadmit.rb

@@ -0,0 +1,55 @@
+# 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
+  class InsufficientScopeError < Error; end
+  class IntrospectionError < Error; end
+
+  ##
+  # Raised when the AgentAdmit introspection endpoint returns HTTP 429 and
+  # all retry attempts (with exponential backoff + jitter) have been exhausted.
+  #
+  # @example
+  #   begin
+  #     client.verify(token)
+  #   rescue AgentAdmit::RateLimitError => e
+  #     render json: { error: 'rate_limited', retry_after: e.retry_after }, status: 429
+  #   end
+  #
+  class RateLimitError < Error
+    # @return [Float, nil] Seconds to wait before retrying (Retry-After header), or nil.
+    attr_reader :retry_after
+    # @return [Integer, nil] X-RateLimit-Limit value, or nil.
+    attr_reader :limit
+    # @return [Integer, nil] X-RateLimit-Remaining value, or nil.
+    attr_reader :remaining
+    # @return [Integer, nil] X-RateLimit-Reset Unix timestamp, or nil.
+    attr_reader :reset
+
+    def initialize(message = "AgentAdmit rate limit exceeded. Max retries exhausted.",
+                   retry_after: nil, limit: nil, remaining: nil, reset: nil)
+      super(message)
+      @retry_after = retry_after
+      @limit       = limit
+      @remaining   = remaining
+      @reset       = reset
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Config.new
+      yield(configuration) if block_given?
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: agentadmit
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Christopher Emerson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Integrate AgentAdmit into your Rails app. Mandatory introspection, scope
+  enforcement, and secure AI agent connections.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/agentadmit.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/version.rb
+homepage: https://agentadmit.com/docs
+licenses:
+- Nonstandard
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: AgentAdmit SDK for Ruby on Rails — User-mediated AI agent authorization
+test_files: []