token_authority 0.1.0 → 0.2.0

data/lib/generators/token_authority/install/templates/token_authority.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+TokenAuthority.configure do |config|
+  # ==========================================================================
+  # General
+  # ==========================================================================
+
+  # The secret key used for signing JWT tokens and generating client secrets.
+  # This should be a secure, random string. By default, it uses the application's
+  # secret_key_base from credentials or configuration.
+  config.secret_key = Rails.application.credentials.secret_key_base || Rails.application.secret_key_base
+
+  # ==========================================================================
+  # JWT Access Tokens (RFC 9068)
+  # ==========================================================================
+
+  # The audience URL for JWT tokens. This is typically your API's base URL.
+  # Used as the "aud" (audience) claim in issued tokens.
+  config.rfc_9068_audience_url = ENV.fetch("TOKEN_AUTHORITY_AUDIENCE_URL", "http://localhost:3000/api/")
+
+  # The issuer URL for JWT tokens. This is typically your application's base URL.
+  # Used as the "iss" (issuer) claim in issued tokens.
+  config.rfc_9068_issuer_url = ENV.fetch("TOKEN_AUTHORITY_ISSUER_URL", "http://localhost:3000/")
+
+  # Default duration for access tokens in seconds (5 minutes).
+  # This value is used when creating new clients without explicit durations.
+  # config.rfc_9068_default_access_token_duration = 300
+
+  # Default duration for refresh tokens in seconds (14 days).
+  # This value is used when creating new clients without explicit durations.
+  # config.rfc_9068_default_refresh_token_duration = 1_209_600
+
+  # ==========================================================================
+  # User Authentication
+  # ==========================================================================
+
+  # The authenticatable controller for the authorization grants controller (consent screen).
+  # This controller must implement:
+  # - authenticate_user! (before_action that ensures user is logged in)
+  # - current_user (returns the currently authenticated user)
+  #
+  # For Devise users, ApplicationController already has these methods.
+  # For other authentication systems, either:
+  # 1. Implement these methods on ApplicationController, or
+  # 2. Set this to a controller that provides these methods
+  # Default: "ApplicationController"
+  # config.authenticatable_controller = "ApplicationController"
+
+  # The class name of your user model. This is used for the belongs_to association
+  # in TokenAuthority::AuthorizationGrant.
+  # Default: "User"
+  # config.user_class = "User"
+
+  # ==========================================================================
+  # UI/Layout
+  # ==========================================================================
+
+  # The layout used for the OAuth consent screen.
+  config.consent_page_layout = "application"
+
+  # The layout used for error pages (e.g., invalid redirect URL).
+  config.error_page_layout = "application"
+
+  # ==========================================================================
+  # Server Metadata (RFC 8414)
+  # ==========================================================================
+
+  # URL to developer documentation for your OAuth server.
+  # Included in the /.well-known/oauth-authorization-server response.
+  # config.rfc_8414_service_documentation = "https://example.com/docs/oauth"
+
+  # Note: scopes_supported in the metadata response is automatically derived
+  # from the keys of config.scopes (see Scopes section below).
+
+  # ==========================================================================
+  # Protected Resource Metadata (RFC 9728)
+  # ==========================================================================
+
+  # The protected resource's identifier URL.
+  # Defaults to rfc_9068_issuer_url if not set.
+  # config.rfc_9728_resource = "https://api.example.com/"
+
+  # Scopes accepted by the protected resource.
+  # Falls back to config.scopes keys if not set.
+  # config.rfc_9728_scopes_supported = ["api:read", "api:write"]
+
+  # List of authorization server issuer URLs that can issue tokens for this resource.
+  # Defaults to the local authorization server (rfc_9068_issuer_url) if not set.
+  # config.rfc_9728_authorization_servers = ["https://auth.example.com"]
+
+  # Token presentation methods supported by the resource (e.g., "header", "body", "query").
+  # config.rfc_9728_bearer_methods_supported = ["header"]
+
+  # URL to the resource's JSON Web Key Set (JWKS).
+  # config.rfc_9728_jwks_uri = "https://api.example.com/.well-known/jwks.json"
+
+  # Human-readable name for the protected resource.
+  # config.rfc_9728_resource_name = "Example API"
+
+  # URL to developer documentation for the protected resource.
+  # config.rfc_9728_resource_documentation = "https://example.com/docs/api"
+
+  # URL to the resource's privacy policy.
+  # config.rfc_9728_resource_policy_uri = "https://example.com/privacy"
+
+  # URL to the resource's terms of service.
+  # config.rfc_9728_resource_tos_uri = "https://example.com/tos"
+
+  # ==========================================================================
+  # Scopes
+  # ==========================================================================
+
+  # Configure allowed scopes with human-friendly display names.
+  # Keys are the scope strings (used as the allowlist), values are display names
+  # shown on the consent screen.
+  #
+  # Set to nil or {} to disable scope validation entirely.
+  # When configured, only these scopes are allowed in authorization requests.
+  # config.scopes = {
+  #   "read" => "Read access to your data",
+  #   "write" => "Write access to your data"
+  # }
+
+  # Require the scope parameter in authorization requests.
+  # When true, clients must specify at least one scope.
+  # config.require_scope = false
+
+  # ==========================================================================
+  # Resource Indicators (RFC 8707)
+  # ==========================================================================
+
+  # Configure allowed resources with human-friendly display names.
+  # Keys are the resource URIs (used as the allowlist), values are display names
+  # shown on the consent screen.
+  #
+  # Set to nil or {} to disable resource indicators entirely.
+  # When configured, only these resources are allowed in authorization requests.
+  # config.rfc_8707_resources = {
+  #   "https://api.example.com/" => "Main API",
+  #   "https://billing.example.com/" => "Billing Service"
+  # }
+
+  # Require the resource parameter in authorization requests.
+  # When true, clients must specify at least one resource.
+  # config.rfc_8707_require_resource = false
+
+  # ==========================================================================
+  # Dynamic Client Registration (RFC 7591)
+  # ==========================================================================
+
+  # Enable dynamic client registration endpoint (/register).
+  # When enabled, clients can register programmatically via POST requests.
+  # Disabled by default for security - enable only if you need this feature.
+  # config.rfc_7591_enabled = false
+
+  # Require an initial access token for client registration.
+  # When enabled, registration requests must include a Bearer token.
+  # config.rfc_7591_require_initial_access_token = false
+
+  # Validator proc for initial access tokens.
+  # Must return true if the token is valid, false otherwise.
+  # Example:
+  # config.rfc_7591_initial_access_token_validator = ->(token) {
+  #   token == ENV["REGISTRATION_ACCESS_TOKEN"]
+  # }
+
+  # Allowed grant types for dynamically registered clients.
+  # config.rfc_7591_allowed_grant_types = %w[authorization_code refresh_token]
+
+  # Allowed response types for dynamically registered clients.
+  # config.rfc_7591_allowed_response_types = %w[code]
+
+  # Allowed token endpoint authentication methods.
+  # Options: none, client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt
+  # config.rfc_7591_allowed_token_endpoint_auth_methods = %w[none client_secret_basic client_secret_post client_secret_jwt private_key_jwt]
+
+  # Client secret expiration duration in seconds (nil = never expires).
+  # config.rfc_7591_client_secret_expiration = nil
+
+  # JWKS for verifying software statements (signed JWTs with client metadata).
+  # Set to a JWKS hash to enable software statement verification.
+  # config.rfc_7591_software_statement_jwks = nil
+
+  # Require software statements for client registration.
+  # When enabled, registration requests must include a valid software_statement.
+  # config.rfc_7591_software_statement_required = false
+
+  # Cache TTL in seconds for fetched JWKS from jwks_uri (default: 1 hour).
+  # config.rfc_7591_jwks_cache_ttl = 3600
+
+  # ==========================================================================
+  # Client Metadata Document (draft-ietf-oauth-client-id-metadata-document)
+  # ==========================================================================
+
+  # URL-based client identifiers allow clients to use HTTPS URLs as their client_id.
+  # The authorization server fetches client metadata from the URL at runtime.
+  # This enables lightweight, decentralized client registration.
+  #
+  # SECURITY CONSIDERATION: By default, any HTTPS URL can be used as a client_id,
+  # meaning any server on the internet can act as an OAuth client to your
+  # authorization server. This is appropriate for MCP servers and open ecosystems.
+  # For restricted access, configure allowed_hosts to limit which domains can
+  # host client metadata documents.
+  #
+  # Example for production with restricted access:
+  #   config.client_metadata_document_allowed_hosts = ["trusted-partner.com", "*.mycompany.com"]
+
+  # Enable URL-based client identifiers (default: true).
+  # config.client_metadata_document_enabled = true
+
+  # Allowed hosts for client metadata document URLs (default: nil = all hosts).
+  # config.client_metadata_document_allowed_hosts = nil
+
+  # Blocked hosts for client metadata document URLs (default: []).
+  # Example: ["internal.example.com", "*.local"]
+  # config.client_metadata_document_blocked_hosts = []
+
+  # Cache TTL in seconds for fetched metadata documents (default: 1 hour).
+  # config.client_metadata_document_cache_ttl = 3600
+
+  # Maximum response size in bytes (default: 5KB).
+  # config.client_metadata_document_max_response_size = 5120
+
+  # Connection and read timeouts in seconds (default: 5 each).
+  # config.client_metadata_document_connect_timeout = 5
+  # config.client_metadata_document_read_timeout = 5
+
+  # ==========================================================================
+  # Event Logging
+  # ==========================================================================
+
+  # TokenAuthority emits structured events using Rails 8.1's event reporting.
+  # Events are automatically logged to Rails.logger when enabled.
+  #
+  # Events include: authorization requests, consent actions, token exchanges,
+  # token refreshes, revocations, client authentication, and security events
+  # (e.g., token theft detection).
+
+  # Enable event logging (default: true).
+  # When enabled, events are emitted and logged to Rails.logger.
+  # config.event_logging_enabled = true
+
+  # Enable debug events (default: false).
+  # Debug events provide detailed information useful during development,
+  # such as PKCE validation steps and cache hits/misses.
+  # config.event_logging_debug_events = false
+end

data/lib/token_authority/configuration.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Configuration class for TokenAuthority engine settings.
+  #
+  # This class manages all configuration options for the OAuth 2.1 provider,
+  # including JWT settings, user authentication integration, UI customization,
+  # and RFC-specific feature flags.
+  #
+  # Configuration is typically set in a Rails initializer using a configure block
+  # that yields this configuration object.
+  #
+  # @example Basic configuration
+  #   TokenAuthority.configure do |config|
+  #     config.secret_key = Rails.application.credentials.secret_key_base
+  #     config.user_class = "User"
+  #     config.rfc_9068_audience_url = "https://api.example.com"
+  #     config.rfc_9068_issuer_url = "https://example.com"
+  #   end
+  #
+  # @example Enabling scopes
+  #   TokenAuthority.configure do |config|
+  #     config.scopes = {
+  #       "read" => "Read access to your data",
+  #       "write" => "Write access to your data"
+  #     }
+  #     config.require_scope = true
+  #   end
+  #
+  # @since 0.2.0
+  class Configuration
+    # @!attribute [rw] secret_key
+    #   The secret key used for JWT signing and HMAC operations.
+    #   This should be a secure random string, typically derived from Rails credentials.
+    #   @return [String] the secret key
+    attr_accessor :secret_key
+
+    # @!attribute [rw] rfc_9068_audience_url
+    #   The default audience (aud) claim for JWT access tokens per RFC 9068.
+    #   Identifies the intended recipient of the token (typically the API server).
+    #   @return [String, nil] the audience URL
+    attr_accessor :rfc_9068_audience_url
+
+    # @!attribute [rw] rfc_9068_issuer_url
+    #   The issuer (iss) claim for JWT access tokens per RFC 9068.
+    #   Identifies the authorization server that issued the token.
+    #   @return [String, nil] the issuer URL
+    attr_accessor :rfc_9068_issuer_url
+
+    # @!attribute [rw] rfc_9068_default_access_token_duration
+    #   Default lifetime for access tokens in seconds.
+    #   @return [Integer] duration in seconds (default: 300)
+    attr_accessor :rfc_9068_default_access_token_duration
+
+    # @!attribute [rw] rfc_9068_default_refresh_token_duration
+    #   Default lifetime for refresh tokens in seconds.
+    #   @return [Integer] duration in seconds (default: 1,209,600)
+    attr_accessor :rfc_9068_default_refresh_token_duration
+
+    # @!attribute [rw] authenticatable_controller
+    #   The controller class name that provides authentication methods.
+    #   Must implement `authenticate_user!` and `current_user` methods.
+    #   @return [String] controller class name (default: "ApplicationController")
+    attr_accessor :authenticatable_controller
+
+    # @!attribute [rw] user_class
+    #   The user model class name in the host application.
+    #   @return [String] user class name (default: "User")
+    attr_accessor :user_class
+
+    # @!attribute [rw] consent_page_layout
+    #   The layout to use for the OAuth consent screen.
+    #   @return [String] layout name (default: "application")
+    attr_accessor :consent_page_layout
+
+    # @!attribute [rw] error_page_layout
+    #   The layout to use for OAuth error pages.
+    #   @return [String] layout name (default: "application")
+    attr_accessor :error_page_layout
+
+    # @!attribute [rw] rfc_8414_service_documentation
+    #   URL for service documentation in authorization server metadata per RFC 8414.
+    #   @return [String, nil] documentation URL
+    attr_accessor :rfc_8414_service_documentation
+
+    # @!attribute [rw] scopes
+    #   Hash mapping scope strings to human-readable descriptions.
+    #   Set to nil or empty hash to disable scopes.
+    #   @example
+    #     config.scopes = {
+    #       "read" => "Read access to your data",
+    #       "write" => "Write access to your data"
+    #     }
+    #   @return [Hash{String => String}, nil] scope mappings
+    attr_accessor :scopes
+
+    # @!attribute [rw] require_scope
+    #   Whether clients must include a scope parameter in authorization requests.
+    #   @return [Boolean] true if scope is required (default: false)
+    attr_accessor :require_scope
+
+    # @!attribute [rw] rfc_9728_resource
+    #   The resource URI for protected resource metadata per RFC 9728.
+    #   @return [String, nil] resource URI
+    attr_accessor :rfc_9728_resource
+
+    # @!attribute [rw] rfc_9728_scopes_supported
+    #   Array of OAuth scopes supported by the protected resource per RFC 9728.
+    #   @return [Array<String>, nil] supported scopes
+    attr_accessor :rfc_9728_scopes_supported
+
+    # @!attribute [rw] rfc_9728_authorization_servers
+    #   Array of authorization server issuer URLs per RFC 9728.
+    #   @return [Array<String>, nil] authorization server URLs
+    attr_accessor :rfc_9728_authorization_servers
+
+    # @!attribute [rw] rfc_9728_bearer_methods_supported
+    #   Array of bearer token methods supported per RFC 9728.
+    #   @return [Array<String>, nil] bearer methods
+    attr_accessor :rfc_9728_bearer_methods_supported
+
+    # @!attribute [rw] rfc_9728_jwks_uri
+    #   URL to the JWKS for protected resource per RFC 9728.
+    #   @return [String, nil] JWKS URI
+    attr_accessor :rfc_9728_jwks_uri
+
+    # @!attribute [rw] rfc_9728_resource_name
+    #   Human-readable name of the protected resource per RFC 9728.
+    #   @return [String, nil] resource name
+    attr_accessor :rfc_9728_resource_name
+
+    # @!attribute [rw] rfc_9728_resource_documentation
+    #   URL to documentation for the protected resource per RFC 9728.
+    #   @return [String, nil] documentation URL
+    attr_accessor :rfc_9728_resource_documentation
+
+    # @!attribute [rw] rfc_9728_resource_policy_uri
+    #   URL to privacy policy for the protected resource per RFC 9728.
+    #   @return [String, nil] policy URI
+    attr_accessor :rfc_9728_resource_policy_uri
+
+    # @!attribute [rw] rfc_9728_resource_tos_uri
+    #   URL to terms of service for the protected resource per RFC 9728.
+    #   @return [String, nil] TOS URI
+    attr_accessor :rfc_9728_resource_tos_uri
+
+    # @!attribute [rw] rfc_7591_enabled
+    #   Enable dynamic client registration per RFC 7591.
+    #   @return [Boolean] true if enabled (default: false)
+    attr_accessor :rfc_7591_enabled
+
+    # @!attribute [rw] rfc_7591_require_initial_access_token
+    #   Require initial access token for client registration per RFC 7591.
+    #   @return [Boolean] true if required (default: false)
+    attr_accessor :rfc_7591_require_initial_access_token
+
+    # @!attribute [rw] rfc_7591_initial_access_token_validator
+    #   Callable object to validate initial access tokens.
+    #   Should accept a token string and return true/false.
+    #   @return [Proc, nil] validator callable
+    attr_accessor :rfc_7591_initial_access_token_validator
+
+    # @!attribute [rw] rfc_7591_allowed_grant_types
+    #   Array of grant types allowed during client registration per RFC 7591.
+    #   @return [Array<String>] allowed grant types
+    attr_accessor :rfc_7591_allowed_grant_types
+
+    # @!attribute [rw] rfc_7591_allowed_response_types
+    #   Array of response types allowed during client registration per RFC 7591.
+    #   @return [Array<String>] allowed response types
+    attr_accessor :rfc_7591_allowed_response_types
+
+    # @!attribute [rw] rfc_7591_allowed_scopes
+    #   Array of scopes allowed during client registration per RFC 7591.
+    #   @return [Array<String>, nil] allowed scopes
+    attr_accessor :rfc_7591_allowed_scopes
+
+    # @!attribute [rw] rfc_7591_allowed_token_endpoint_auth_methods
+    #   Array of token endpoint authentication methods allowed per RFC 7591.
+    #   @return [Array<String>] allowed auth methods
+    attr_accessor :rfc_7591_allowed_token_endpoint_auth_methods
+
+    # @!attribute [rw] rfc_7591_client_secret_expiration
+    #   Duration in seconds before client secrets expire, or nil for no expiration.
+    #   @return [Integer, nil] expiration duration in seconds
+    attr_accessor :rfc_7591_client_secret_expiration
+
+    # @!attribute [rw] rfc_7591_software_statement_jwks
+    #   JWKS for verifying software statements during registration per RFC 7591.
+    #   @return [Hash, nil] JWKS
+    attr_accessor :rfc_7591_software_statement_jwks
+
+    # @!attribute [rw] rfc_7591_software_statement_required
+    #   Require software statements during client registration per RFC 7591.
+    #   @return [Boolean] true if required (default: false)
+    attr_accessor :rfc_7591_software_statement_required
+
+    # @!attribute [rw] rfc_7591_jwks_cache_ttl
+    #   Time-to-live for cached JWKS in seconds.
+    #   @return [Integer] TTL in seconds (default: 3600)
+    attr_accessor :rfc_7591_jwks_cache_ttl
+
+    # @!attribute [rw] client_metadata_document_enabled
+    #   Enable support for client metadata documents (URL-based client IDs).
+    #   @return [Boolean] true if enabled (default: true)
+    attr_accessor :client_metadata_document_enabled
+
+    # @!attribute [rw] client_metadata_document_cache_ttl
+    #   Time-to-live for cached client metadata documents in seconds.
+    #   @return [Integer] TTL in seconds (default: 3600)
+    attr_accessor :client_metadata_document_cache_ttl
+
+    # @!attribute [rw] client_metadata_document_max_response_size
+    #   Maximum size in bytes for client metadata document HTTP responses.
+    #   @return [Integer] max size in bytes (default: 5120)
+    attr_accessor :client_metadata_document_max_response_size
+
+    # @!attribute [rw] client_metadata_document_allowed_hosts
+    #   Whitelist of hosts allowed for client metadata document URLs.
+    #   @return [Array<String>, nil] allowed hosts
+    attr_accessor :client_metadata_document_allowed_hosts
+
+    # @!attribute [rw] client_metadata_document_blocked_hosts
+    #   Blacklist of hosts blocked for client metadata document URLs.
+    #   @return [Array<String>] blocked hosts (default: [])
+    attr_accessor :client_metadata_document_blocked_hosts
+
+    # @!attribute [rw] client_metadata_document_connect_timeout
+    #   Connection timeout in seconds for fetching client metadata documents.
+    #   @return [Integer] timeout in seconds (default: 5)
+    attr_accessor :client_metadata_document_connect_timeout
+
+    # @!attribute [rw] client_metadata_document_read_timeout
+    #   Read timeout in seconds for fetching client metadata documents.
+    #   @return [Integer] timeout in seconds (default: 5)
+    attr_accessor :client_metadata_document_read_timeout
+
+    # @!attribute [rw] rfc_8707_resources
+    #   Hash mapping resource URIs to human-readable descriptions per RFC 8707.
+    #   Set to nil or empty hash to disable resource indicators.
+    #   @example
+    #     config.rfc_8707_resources = {
+    #       "https://api.example.com" => "Main API",
+    #       "https://files.example.com" => "File Storage API"
+    #     }
+    #   @return [Hash{String => String}, nil] resource mappings
+    attr_accessor :rfc_8707_resources
+
+    # @!attribute [rw] rfc_8707_require_resource
+    #   Whether clients must include a resource parameter per RFC 8707.
+    #   @return [Boolean] true if required (default: false)
+    attr_accessor :rfc_8707_require_resource
+
+    # @!attribute [rw] event_logging_enabled
+    #   Enable structured event logging for OAuth flows and security events.
+    #   @return [Boolean] true if enabled (default: true)
+    attr_accessor :event_logging_enabled
+
+    # @!attribute [rw] event_logging_debug_events
+    #   Enable debug-level event logging for troubleshooting.
+    #   @return [Boolean] true if enabled (default: false)
+    attr_accessor :event_logging_debug_events
+
+    # @!attribute [rw] instrumentation_enabled
+    #   Enable ActiveSupport::Notifications instrumentation for performance monitoring.
+    #   @return [Boolean] true if enabled (default: true)
+    attr_accessor :instrumentation_enabled
+
+    def initialize
+      # General
+      @secret_key = nil
+
+      # User Authentication
+      @authenticatable_controller = "ApplicationController"
+      @user_class = "User"
+
+      # UI/Layout
+      @consent_page_layout = "application"
+      @error_page_layout = "application"
+
+      # Scopes
+      @scopes = nil
+      @require_scope = false
+
+      # JWT Access Tokens (RFC 9068)
+      @rfc_9068_audience_url = nil
+      @rfc_9068_issuer_url = nil
+      @rfc_9068_default_access_token_duration = 300 # 5 minutes in seconds
+      @rfc_9068_default_refresh_token_duration = 1_209_600 # 14 days in seconds
+
+      # Server Metadata (RFC 8414)
+      @rfc_8414_service_documentation = nil
+
+      # Protected Resource Metadata (RFC 9728)
+      @rfc_9728_resource = nil
+      @rfc_9728_scopes_supported = nil
+      @rfc_9728_authorization_servers = nil
+      @rfc_9728_bearer_methods_supported = nil
+      @rfc_9728_jwks_uri = nil
+      @rfc_9728_resource_name = nil
+      @rfc_9728_resource_documentation = nil
+      @rfc_9728_resource_policy_uri = nil
+      @rfc_9728_resource_tos_uri = nil
+
+      # Dynamic Client Registration (RFC 7591)
+      @rfc_7591_enabled = false
+      @rfc_7591_require_initial_access_token = false
+      @rfc_7591_initial_access_token_validator = nil
+      @rfc_7591_allowed_grant_types = %w[authorization_code refresh_token]
+      @rfc_7591_allowed_response_types = %w[code]
+      @rfc_7591_allowed_scopes = nil
+      @rfc_7591_allowed_token_endpoint_auth_methods = %w[none client_secret_basic client_secret_post client_secret_jwt private_key_jwt]
+      @rfc_7591_client_secret_expiration = nil
+      @rfc_7591_software_statement_jwks = nil
+      @rfc_7591_software_statement_required = false
+      @rfc_7591_jwks_cache_ttl = 3600
+
+      # Client Metadata Document (draft-ietf-oauth-client-id-metadata-document)
+      @client_metadata_document_enabled = true
+      @client_metadata_document_cache_ttl = 3600
+      @client_metadata_document_max_response_size = 5120
+      @client_metadata_document_allowed_hosts = nil
+      @client_metadata_document_blocked_hosts = []
+      @client_metadata_document_connect_timeout = 5
+      @client_metadata_document_read_timeout = 5
+
+      # Resource Indicators (RFC 8707)
+      @rfc_8707_resources = nil
+      @rfc_8707_require_resource = false
+
+      # Event Logging
+      @event_logging_enabled = true
+      @event_logging_debug_events = false
+
+      # Instrumentation
+      @instrumentation_enabled = true
+    end
+
+    # Checks whether the scopes feature is enabled.
+    # Scopes are considered enabled when the scopes attribute is a non-empty hash.
+    #
+    # @return [Boolean] true if scopes are enabled
+    def scopes_enabled?
+      scopes.is_a?(Hash) && scopes.any?
+    end
+
+    # Checks whether RFC 8707 resource indicators are enabled.
+    # Resource indicators are considered enabled when rfc_8707_resources is a non-empty hash.
+    #
+    # @return [Boolean] true if resource indicators are enabled
+    def rfc_8707_enabled?
+      rfc_8707_resources.is_a?(Hash) && rfc_8707_resources.any?
+    end
+
+    # Validates the configuration for internal consistency.
+    # Ensures that required features are properly configured before use.
+    #
+    # @raise [ConfigurationError] if require_scope is true but scopes are not configured
+    # @raise [ConfigurationError] if rfc_8707_require_resource is true but resources are not configured
+    # @return [void]
+    def validate!
+      if require_scope && !scopes_enabled?
+        raise ConfigurationError, "require_scope is true but no scopes are configured"
+      end
+
+      if rfc_8707_require_resource && !rfc_8707_enabled?
+        raise ConfigurationError, "rfc_8707_require_resource is true but no rfc_8707_resources are configured"
+      end
+    end
+  end
+
+  class << self
+    # Returns the current configuration instance.
+    # Creates a new configuration with default values if one doesn't exist.
+    #
+    # @return [Configuration] the configuration instance
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the configuration instance for setup in initializers.
+    # This is the primary way to configure TokenAuthority in a Rails application.
+    #
+    # @example
+    #   TokenAuthority.configure do |config|
+    #     config.secret_key = Rails.application.credentials.secret_key_base
+    #     config.user_class = "User"
+    #   end
+    #
+    # @yield [config] configuration block
+    # @yieldparam config [Configuration] the configuration instance to modify
+    # @return [void]
+    def configure
+      yield(config)
+    end
+  end
+end

data/lib/token_authority/engine.rb

@@ -1,5 +1,39 @@
 module TokenAuthority
+  # Rails engine that integrates TokenAuthority into host applications.
+  #
+  # The engine uses an isolated namespace to avoid conflicts with the host application's
+  # models and controllers. It sets up initializers for event logging and instrumentation
+  # based on the configuration settings.
+  #
+  # @note This engine is automatically loaded when the TokenAuthority gem is required
+  #   in a Rails application.
+  #
+  # @since 0.2.0
   class Engine < ::Rails::Engine
     isolate_namespace TokenAuthority
+
+    # Registers the event subscriber to capture and log OAuth flow events.
+    # Only runs if event_logging_enabled is true in the configuration.
+    #
+    # Events are published through Rails.event and include authorization grants,
+    # token exchanges, and security-related activities.
+    initializer "token_authority.event_logging", after: :load_config_initializers do
+      if TokenAuthority.config.event_logging_enabled
+        require "token_authority/log_event_subscriber"
+        Rails.event.subscribe(TokenAuthority::LogEventSubscriber.new)
+      end
+    end
+
+    # Attaches the instrumentation log subscriber to capture performance metrics.
+    # Only runs if instrumentation_enabled is true in the configuration.
+    #
+    # Instrumentation uses ActiveSupport::Notifications to track timing and
+    # performance of key operations like JWT encoding/decoding and session creation.
+    initializer "token_authority.instrumentation", after: :load_config_initializers do
+      if TokenAuthority.config.instrumentation_enabled
+        require "token_authority/instrumentation_log_subscriber"
+        TokenAuthority::InstrumentationLogSubscriber.subscribe!
+      end
+    end
   end
 end