Module: Hooks::App::Auth

Included in:
API
Defined in:
lib/hooks/app/auth/auth.rb

Overview

Provides authentication helpers for verifying incoming requests.

Examples:

Usage

include Hooks::App::Auth
validate_auth!(payload, headers, endpoint_config)

Instance Method Summary collapse

Instance Method Details

#validate_auth!(payload, headers, endpoint_config, global_config = {}, request_context = {}) ⇒ void

Note:

This method will halt execution with an error if authentication fails.

This method returns an undefined value.

Verifies the incoming request using the configured authentication method.

Parameters:

  • payload (String, Hash) —

    The request payload to authenticate.

  • headers (Hash) —

    The request headers.

  • endpoint_config (Hash) —

    The endpoint configuration, must include :auth key.

  • global_config (Hash) (defaults to: {}) —

    The global configuration (optional, for compatibility).

  • request_context (Hash) (defaults to: {}) —

    Context for the request, e.g. request ID, path, handler (optional).

Raises:

  • (StandardError) —

    Raises error if authentication fails or is misconfigured.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/hooks/app/auth/auth.rb', line 23

def validate_auth!(payload, headers, endpoint_config, global_config = {}, request_context = {})
  auth_config = endpoint_config[:auth]
  request_id = request_context&.dig(:request_id)

  # Ensure auth type is present and valid
  auth_type = auth_config&.dig(:type)
  unless auth_type&.is_a?(String) && !auth_type.strip.empty?
    log.error("authentication configuration missing or invalid - request_id: #{request_id}")
    error!({
      error: "authentication_configuration_error",
      message: "authentication configuration missing or invalid",
      request_id:
    }, 500)
  end

  # Get auth plugin from loaded plugins registry (boot-time loaded only)
  begin
    auth_class = Core::PluginLoader.get_auth_plugin(auth_type)
  rescue => e
    log.error("failed to load auth plugin '#{auth_type}': #{e.message} - request_id: #{request_id}")
    error!({
      error: "authentication_plugin_error",
      message: "unsupported auth type '#{auth_type}'",
      request_id:
    }, 400)
  end

  log.debug("validating auth for request with auth_class: #{auth_class.name}")
  unless auth_class.valid?(payload:, headers:, config: endpoint_config)
    log.warn("authentication failed for request with auth_class: #{auth_class.name} - request_id: #{request_id}")
    error!({
      error: "authentication_failed",
      message: "authentication failed",
      request_id:
    }, 401)
  end
end