agentsid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 796f78999826a0414ab444d8064b49b86225a2b756709b3f2fe87b3ba237232b
+  data.tar.gz: 358114838c3cbb6e50eb24bb51afcb6af141ee1c9bb646821dde80f3686d3cc8
+SHA512:
+  metadata.gz: c36cc8d5ffff7db25ce08b52d9f0097cfb4332ee1c87f05591c60887e7e93fa86202e0ddc69f7d79bb873bef0562433a2022e3e5a64cd3652362ba99d4477059
+  data.tar.gz: 6cf73da1f2342d7a58ec313ed07fd7753b292e1e3c17306d182c7f717a4b02b48d4610078e230b15deb3f0885efb97ee640d556d8020b211f245cad88c5fd3b4

data/agentsid.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "agentsid"
+  spec.version       = "0.1.0"
+  spec.authors       = ["AgentsID"]
+  spec.email         = ["support@agentsid.dev"]
+
+  spec.summary       = "Ruby SDK for AgentsID — agent identity, permissions, and audit for AI tools"
+  spec.description   = "Register AI agents, issue scoped tokens, enforce per-tool permissions, " \
+                        "and query audit logs via the AgentsID API. Includes MCP middleware for " \
+                        "validating tool calls in MCP servers."
+  spec.homepage      = "https://agentsid.dev"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.files         = Dir["lib/**/*.rb"] + ["agentsid.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.metadata = {
+    "homepage_uri"    => spec.homepage,
+    "source_code_uri" => "https://github.com/agentsid/sdk-ruby",
+    "bug_tracker_uri" => "https://github.com/agentsid/sdk-ruby/issues"
+  }
+end

data/lib/agentsid/client.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "errors"
+
+module AgentsID
+  DEFAULT_BASE_URL = "https://agentsid.dev"
+  DEFAULT_TIMEOUT = 10
+
+  # AgentsID client -- register agents, validate tokens, manage permissions.
+  class Client
+    # @param project_key [String] Your AgentsID project key (aid_proj_...)
+    # @param base_url [String] AgentsID server URL
+    # @param timeout [Integer] HTTP timeout in seconds
+    def initialize(project_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      raise AgentsIDError.new("project_key is required", code: "CONFIG_ERROR") if project_key.nil? || project_key.empty?
+
+      @project_key = project_key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+    end
+
+    # -----------------------------------------------------------
+    # AGENTS
+    # -----------------------------------------------------------
+
+    # Register a new agent identity and issue a token.
+    #
+    # @param name [String]
+    # @param on_behalf_of [String]
+    # @param permissions [Array<String>, nil]
+    # @param ttl_hours [Integer, nil]
+    # @param metadata [Hash, nil]
+    # @return [Hash]
+    def register_agent(name:, on_behalf_of:, permissions: nil, ttl_hours: nil, metadata: nil)
+      request(:post, "/agents/", {
+        name: name,
+        on_behalf_of: on_behalf_of,
+        permissions: permissions,
+        ttl_hours: ttl_hours,
+        metadata: metadata
+      })
+    end
+
+    # @param agent_id [String]
+    # @return [Hash]
+    def get_agent(agent_id)
+      request(:get, "/agents/#{agent_id}")
+    end
+
+    # @param status [String, nil] Filter by status
+    # @param limit [Integer] Max results (default 50)
+    # @return [Array<Hash>]
+    def list_agents(status: nil, limit: 50)
+      params = {}
+      params[:status] = status if status
+      params[:limit] = limit if limit != 50
+      qs = URI.encode_www_form(params)
+      path = qs.empty? ? "/agents/" : "/agents/?#{qs}"
+      request(:get, path)
+    end
+
+    # @param agent_id [String]
+    # @return [Hash]
+    def revoke_agent(agent_id)
+      request(:delete, "/agents/#{agent_id}")
+    end
+
+    # -----------------------------------------------------------
+    # PERMISSIONS
+    # -----------------------------------------------------------
+
+    # Set permission rules for an agent.
+    #
+    # @param agent_id [String]
+    # @param rules [Array<Hash>] Each rule: { tool_pattern: "...", action: "allow"|"deny" }
+    # @return [Hash]
+    def set_permissions(agent_id, rules)
+      body = rules.map do |r|
+        {
+          tool_pattern: r[:tool_pattern] || r["tool_pattern"] || r[:toolPattern] || r["toolPattern"] || "",
+          action: r[:action] || r["action"] || "allow",
+          conditions: r[:conditions] || r["conditions"],
+          priority: r[:priority] || r["priority"] || 0
+        }
+      end
+      request(:put, "/agents/#{agent_id}/permissions", body)
+    end
+
+    # @param agent_id [String]
+    # @return [Array<Hash>]
+    def get_permissions(agent_id)
+      data = request(:get, "/agents/#{agent_id}/permissions")
+      data.fetch("rules", [])
+    end
+
+    # @param agent_id [String]
+    # @param tool [String]
+    # @param params [Hash, nil]
+    # @return [Hash]
+    def check_permission(agent_id, tool, params: nil)
+      request(:post, "/check", {
+        agent_id: agent_id,
+        tool: tool,
+        params: params
+      })
+    end
+
+    # -----------------------------------------------------------
+    # TOKEN VALIDATION
+    # -----------------------------------------------------------
+
+    # @param token [String]
+    # @param tool [String, nil]
+    # @param params [Hash, nil]
+    # @return [Hash]
+    def validate_token(token, tool: nil, params: nil)
+      request(:post, "/validate", {
+        token: token,
+        tool: tool,
+        params: params
+      })
+    end
+
+    # -----------------------------------------------------------
+    # AUDIT
+    # -----------------------------------------------------------
+
+    # @param agent_id [String, nil]
+    # @param tool [String, nil]
+    # @param action [String, nil]
+    # @param since [String, nil] ISO 8601 timestamp
+    # @param limit [Integer]
+    # @return [Hash]
+    def get_audit_log(agent_id: nil, tool: nil, action: nil, since: nil, limit: 100)
+      params = {}
+      params[:agent_id] = agent_id if agent_id
+      params[:tool] = tool if tool
+      params[:action] = action if action
+      params[:since] = since if since
+      params[:limit] = limit
+      qs = URI.encode_www_form(params)
+      request(:get, "/audit/?#{qs}")
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      uri = URI("#{@base_url}/api/v1#{path}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      req = build_request(method, uri, body)
+
+      response = http.request(req)
+
+      handle_response(response)
+    end
+
+    def build_request(method, uri, body)
+      klass = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@project_key}"
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body) if body
+      req
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+
+      raise AuthenticationError.new if status == 401
+      return {} if status == 204
+
+      data = JSON.parse(response.body)
+
+      unless (200..299).cover?(status)
+        message = data["detail"] || "Request failed: #{status}"
+        raise AgentsIDError.new(message, code: "API_ERROR", status_code: status)
+      end
+
+      data
+    end
+  end
+end

data/lib/agentsid/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module AgentsID
+  class AgentsIDError < StandardError
+    attr_reader :code, :status_code
+
+    def initialize(message, code: "UNKNOWN", status_code: nil)
+      super(message)
+      @code = code
+      @status_code = status_code
+    end
+  end
+
+  class AuthenticationError < AgentsIDError
+    def initialize(message = "Invalid or missing API key")
+      super(message, code: "AUTH_ERROR", status_code: 401)
+    end
+  end
+
+  class PermissionDeniedError < AgentsIDError
+    attr_reader :tool, :reason
+
+    def initialize(tool, reason)
+      @tool = tool
+      @reason = reason
+      super(
+        "Permission denied for tool \"#{tool}\": #{reason}",
+        code: "PERMISSION_DENIED",
+        status_code: 403
+      )
+    end
+  end
+
+  class TokenExpiredError < AgentsIDError
+    def initialize
+      super("Agent token has expired", code: "TOKEN_EXPIRED", status_code: 401)
+    end
+  end
+
+  class TokenRevokedError < AgentsIDError
+    def initialize
+      super("Agent token has been revoked", code: "TOKEN_REVOKED", status_code: 401)
+    end
+  end
+end

data/lib/agentsid/middleware.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "errors"
+
+module AgentsID
+  DEFAULT_BASE_URL_MW = "https://agentsid.dev"
+
+  # Validate a single tool call against AgentsID.
+  #
+  # @param project_key [String]
+  # @param token [String]
+  # @param tool [String]
+  # @param params [Hash, nil]
+  # @param base_url [String]
+  # @return [Hash]
+  def self.validate_tool_call(project_key:, token:, tool:, params: nil, base_url: DEFAULT_BASE_URL_MW)
+    uri = URI("#{base_url.chomp('/')}/api/v1/validate")
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == "https"
+    http.open_timeout = 10
+    http.read_timeout = 10
+
+    req = Net::HTTP::Post.new(uri)
+    req["Content-Type"] = "application/json"
+    req.body = JSON.generate({ token: token, tool: tool, params: params })
+
+    response = http.request(req)
+    status = response.code.to_i
+
+    unless (200..299).cover?(status)
+      return { "valid" => false, "reason" => "Validation failed: #{status}" }
+    end
+
+    JSON.parse(response.body)
+  end
+
+  # MCP middleware -- validates tool calls against AgentsID.
+  #
+  # Usage:
+  #   middleware = AgentsID::MCPMiddleware.new(project_key: "aid_proj_...")
+  #
+  #   # In your MCP tool handler:
+  #   result = middleware.validate(bearer_token, "my_tool", params)
+  class MCPMiddleware
+    # @param project_key [String] Your AgentsID project key
+    # @param base_url [String] AgentsID server URL
+    # @param skip_tools [Array<String>, nil] Tool names to skip validation for
+    # @param on_denied [Proc, nil] Callback invoked on denial instead of raising
+    def initialize(project_key:, base_url: DEFAULT_BASE_URL_MW, skip_tools: nil, on_denied: nil)
+      @project_key = project_key
+      @base_url = base_url.chomp("/")
+      @skip_tools = Set.new(skip_tools || [])
+      @on_denied = on_denied
+    end
+
+    # Validate a tool call. Raises on denial unless on_denied is set.
+    #
+    # @param token [String]
+    # @param tool [String]
+    # @param params [Hash, nil]
+    # @return [Hash]
+    def validate(token, tool, params = nil)
+      if @skip_tools.include?(tool)
+        return { "valid" => true, "reason" => "Tool in skip list" }
+      end
+
+      result = AgentsID.validate_tool_call(
+        project_key: @project_key,
+        token: token,
+        tool: tool,
+        params: params,
+        base_url: @base_url
+      )
+
+      unless result["valid"]
+        reason = result["reason"] || "Unknown"
+        raise TokenExpiredError.new if reason.include?("expired")
+        raise TokenRevokedError.new if reason.include?("revoked")
+      end
+
+      permission = result["permission"] || {}
+      if permission.any? && !permission["allowed"]
+        denial_reason = permission["reason"] || "Denied"
+        if @on_denied
+          @on_denied.call(tool, denial_reason)
+        else
+          raise PermissionDeniedError.new(tool, denial_reason)
+        end
+      end
+
+      result
+    end
+
+    # Quick check -- returns true/false without raising.
+    #
+    # @param token [String]
+    # @param tool [String]
+    # @return [Boolean]
+    def allowed?(token, tool)
+      result = AgentsID.validate_tool_call(
+        project_key: @project_key,
+        token: token,
+        tool: tool,
+        base_url: @base_url
+      )
+      result["valid"] == true && result.dig("permission", "allowed") == true
+    rescue StandardError
+      false
+    end
+  end
+
+  # Factory method matching the Python SDK's create_mcp_middleware.
+  #
+  # @param project_key [String]
+  # @param base_url [String]
+  # @param skip_tools [Array<String>, nil]
+  # @return [MCPMiddleware]
+  def self.create_mcp_middleware(project_key:, base_url: DEFAULT_BASE_URL_MW, skip_tools: nil)
+    MCPMiddleware.new(
+      project_key: project_key,
+      base_url: base_url,
+      skip_tools: skip_tools
+    )
+  end
+end

data/lib/agentsid.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "agentsid/errors"
+require_relative "agentsid/client"
+require_relative "agentsid/middleware"
+
+module AgentsID
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: agentsid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AgentsID
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-26 00:00:00.000000000 Z
+dependencies: []
+description: Register AI agents, issue scoped tokens, enforce per-tool permissions,
+  and query audit logs via the AgentsID API. Includes MCP middleware for validating
+  tool calls in MCP servers.
+email:
+- support@agentsid.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- agentsid.gemspec
+- lib/agentsid.rb
+- lib/agentsid/client.rb
+- lib/agentsid/errors.rb
+- lib/agentsid/middleware.rb
+homepage: https://agentsid.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://agentsid.dev
+  source_code_uri: https://github.com/agentsid/sdk-ruby
+  bug_tracker_uri: https://github.com/agentsid/sdk-ruby/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.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: Ruby SDK for AgentsID — agent identity, permissions, and audit for AI tools
+test_files: []