Class: A2A::Client::Auth::ApiKey

Inherits:
Object
  • Object
show all
Defined in:
lib/a2a/client/auth/api_key.rb

Constant Summary collapse

VALID_LOCATIONS =

Valid locations for API key

%w[header query cookie].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key:, name: "X-API-Key", location: "header") ⇒ ApiKey

Initialize API key authentication

Parameters:

  • key (String) —

    The API key value

  • name (String) (defaults to: "X-API-Key") —

    The parameter/header name for the API key (default: 'X-API-Key')

  • location (String) (defaults to: "header") —

    Where to place the API key: 'header', 'query', or 'cookie' (default: 'header')



24
25
26
27
28
29
30
31
 
# File 'lib/a2a/client/auth/api_key.rb', line 24

def initialize(key:, name: "X-API-Key", location: "header")
  @key = key
  @name = name
  @location = location.downcase
  @value = key # Alias for consistency

  validate_configuration!
end

Instance Attribute Details

#key ⇒ Object (readonly)

Returns the value of attribute key.



13
14
15
 
# File 'lib/a2a/client/auth/api_key.rb', line 13

def key
  @key
end

#location ⇒ Object (readonly)

Returns the value of attribute location.



13
14
15
 
# File 'lib/a2a/client/auth/api_key.rb', line 13

def location
  @location
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/a2a/client/auth/api_key.rb', line 13

def name
  @name
end

#value ⇒ Object (readonly)

Returns the value of attribute value.



13
14
15
 
# File 'lib/a2a/client/auth/api_key.rb', line 13

def value
  @value
end

Class Method Details

.from_security_scheme(scheme, key_value) ⇒ ApiKey

Create API key authentication from security scheme

Parameters:

  • scheme (Hash) —

    Security scheme definition

  • key_value (String) —

    The API key value

Returns:

  • (ApiKey) —

    Configured API key authentication



102
103
104
105
106
107
 
# File 'lib/a2a/client/auth/api_key.rb', line 102

def self.from_security_scheme(scheme, key_value)
  location = scheme["in"] || "header"
  name = scheme["name"] || "X-API-Key"

  new(key: key_value, name: name, location: location)
end

Instance Method Details

#apply_to_request(request) ⇒ Object

Apply authentication to a Faraday request

Parameters:

  • request (Faraday::Request) —

    The request to authenticate



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/a2a/client/auth/api_key.rb', line 37

def apply_to_request(request)
  case @location
  when "header"
    request.headers[@name] = @key
  when "query"
    # Add to query parameters
    request.params[@name] = @key
  when "cookie"
    # Add to cookie header
    existing_cookies = request.headers["Cookie"]
    cookie_value = "#{@name}=#{@key}"

    request.headers["Cookie"] = if existing_cookies
                                  "#{existing_cookies}; #{cookie_value}"
                                else
                                  cookie_value
                                end
  end
end

#authentication_header ⇒ Hash

Get the authentication header (for header-based API keys)

Returns:

  • (Hash) —

    Header name and value



61
62
63
64
65
 
# File 'lib/a2a/client/auth/api_key.rb', line 61

def authentication_header
  return {} unless @location == "header"

  { @name => @key }
end

#authentication_params ⇒ Hash

Get the authentication query parameter (for query-based API keys)

Returns:

  • (Hash) —

    Parameter name and value



71
72
73
74
75
 
# File 'lib/a2a/client/auth/api_key.rb', line 71

def authentication_params
  return {} unless @location == "query"

  { @name => @key }
end

#inspect ⇒ String

Inspect representation (with masked key)

Returns:

  • (String) —

    Inspect representation



134
135
136
 
# File 'lib/a2a/client/auth/api_key.rb', line 134

def inspect
  "#<A2A::Client::Auth::ApiKey:0x#{object_id.to_s(16)} #{self}>"
end

#masked_key ⇒ String

Mask the API key for logging (shows only first and last 4 characters)

Returns:

  • (String) —

    Masked API key



89
90
91
92
93
94
 
# File 'lib/a2a/client/auth/api_key.rb', line 89

def masked_key
  return "[empty]" if @key.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
  return @key if @key.length <= 8

  "#{@key[0..3]}#{'*' * (@key.length - 8)}#{@key[-4..]}"
end

#to_h ⇒ Hash

Convert to hash representation

Returns:

  • (Hash) —

    Configuration as hash



113
114
115
116
117
118
119
120
 
# File 'lib/a2a/client/auth/api_key.rb', line 113

def to_h
  {
    type: "api_key",
    key: masked_key,
    name: @name,
    location: @location
  }
end

#to_s ⇒ String

String representation (with masked key)

Returns:

  • (String) —

    String representation



126
127
128
 
# File 'lib/a2a/client/auth/api_key.rb', line 126

def to_s
  "ApiKey(name=#{@name}, location=#{@location}, key=#{masked_key})"
end

#valid? ⇒ Boolean

Check if the API key is valid (basic validation)

Returns:

  • (Boolean) —

    True if key appears valid



81
82
83
 
# File 'lib/a2a/client/auth/api_key.rb', line 81

def valid?
  @key.present? && @key.is_a?(String)
end

#validate_configuration! ⇒ Object (private)

Validate the authentication configuration

Raises:

  • (ArgumentError) 


142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/a2a/client/auth/api_key.rb', line 142

def validate_configuration!
  if @key.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
    raise ArgumentError,
          "API key cannot be nil or empty"
  end
  raise ArgumentError, "API key must be a string" unless @key.is_a?(String)

  if @name.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
    raise ArgumentError,
          "Name cannot be nil or empty"
  end

  return if VALID_LOCATIONS.include?(@location)

  raise ArgumentError, "Invalid location '#{@location}'. Must be one of: #{VALID_LOCATIONS.join(', ')}"
end