token_authority 0.1.0 → 0.2.0

data/lib/token_authority/errors.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Raised when the TokenAuthority configuration is invalid or inconsistent.
+  # This typically occurs during initialization or validation when required
+  # configuration options are missing or conflicting.
+  #
+  # @since 0.2.0
+  class ConfigurationError < StandardError; end
+
+  # Raised when the client attempting to use a token or grant doesn't match
+  # the client that originally requested it. This prevents token theft and
+  # unauthorized client access.
+  #
+  # @since 0.2.0
+  class ClientMismatchError < StandardError; end
+
+  # Raised when a requested OAuth client cannot be found in the database or
+  # via client metadata document resolution.
+  #
+  # @since 0.2.0
+  class ClientNotFoundError < StandardError; end
+
+  # Raised when an access token fails validation (expired, malformed, or invalid signature).
+  #
+  # @since 0.2.0
+  class InvalidAccessTokenError < StandardError; end
+
+  # Raised when an authorization grant is invalid, expired, already redeemed,
+  # or the PKCE code verifier doesn't match the challenge.
+  #
+  # Uses I18n for the error message to support internationalization.
+  #
+  # @since 0.2.0
+  class InvalidGrantError < StandardError
+    # Returns the localized error message.
+    # @return [String] the error message
+    def message
+      I18n.t("token_authority.errors.invalid_grant")
+    end
+  end
+
+  # Raised when a client's redirect URI cannot be parsed or is otherwise invalid.
+  # This prevents open redirect vulnerabilities.
+  #
+  # @since 0.2.0
+  class InvalidRedirectUrlError < StandardError; end
+
+  # Raised when a protected endpoint is accessed without the required Authorization header.
+  #
+  # @since 0.2.0
+  class MissingAuthorizationHeaderError < StandardError; end
+
+  # Raised when an OAuth session cannot be found by token JTI or session ID.
+  #
+  # @since 0.2.0
+  class OAuthSessionNotFound < StandardError; end
+
+  # Raised when attempting to use a revoked session.
+  # This can indicate a refresh token replay attack where a stolen token
+  # is used after the legitimate client has already refreshed.
+  #
+  # Captures context about both the session being refreshed and the session
+  # that was revoked to aid in security auditing.
+  #
+  # @since 0.2.0
+  class RevokedSessionError < StandardError
+    # @return [String] the client ID that attempted the refresh
+    attr_reader :client_id
+
+    # @return [Integer] the session ID that was being refreshed
+    attr_reader :refreshed_session_id
+
+    # @return [Integer] the session ID that was revoked
+    attr_reader :revoked_session_id
+
+    # @return [Integer] the user ID associated with the session
+    attr_reader :user_id
+
+    # Creates a new RevokedSessionError with security context.
+    #
+    # @param client_id [String] the client ID
+    # @param refreshed_session_id [Integer] the session being refreshed
+    # @param revoked_session_id [Integer] the session that was revoked
+    # @param user_id [Integer] the user ID
+    def initialize(client_id:, refreshed_session_id:, revoked_session_id:, user_id:)
+      super()
+      @client_id = client_id
+      @refreshed_session_id = refreshed_session_id
+      @revoked_session_id = revoked_session_id
+      @user_id = user_id
+    end
+
+    # Returns the localized error message with context.
+    # @return [String] the error message
+    def message
+      I18n.t("token_authority.errors.revoked_session", client_id:, refreshed_session_id:, revoked_session_id:, user_id:)
+    end
+  end
+
+  # Raised for unexpected server-side errors during OAuth flows.
+  # This is a catch-all for internal processing errors.
+  #
+  # @since 0.2.0
+  class ServerError < StandardError; end
+
+  # Raised when an access token is valid but the user is not authorized
+  # to access the requested resource.
+  #
+  # @since 0.2.0
+  class UnauthorizedAccessTokenError < StandardError; end
+
+  # Raised when PKCE code challenge verification fails.
+  # This indicates the code_verifier doesn't match the original code_challenge,
+  # which could indicate an interception attack.
+  #
+  # @since 0.2.0
+  class UnsuccessfulChallengeError < StandardError; end
+
+  # Raised when a client requests a grant type that is not supported
+  # by the authorization server.
+  #
+  # @since 0.2.0
+  class UnsupportedGrantTypeError < StandardError; end
+
+  # Raised during client registration (RFC 7591) when one or more
+  # redirect URIs are malformed or use an invalid scheme.
+  #
+  # @since 0.2.0
+  class InvalidRedirectUrisError < StandardError
+    # Creates a new InvalidRedirectUrisError.
+    # @param msg [String] custom error message
+    def initialize(msg = "One or more redirect_uris are invalid")
+      super
+    end
+  end
+
+  # Raised during client registration (RFC 7591) when the submitted
+  # client metadata fails validation.
+  #
+  # @since 0.2.0
+  class InvalidClientMetadataError < StandardError
+    # Creates a new InvalidClientMetadataError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Client metadata is invalid")
+      super
+    end
+  end
+
+  # Raised during client registration (RFC 7591) when a software statement
+  # JWT cannot be verified or contains invalid claims.
+  #
+  # @since 0.2.0
+  class InvalidSoftwareStatementError < StandardError
+    # Creates a new InvalidSoftwareStatementError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Software statement is invalid or could not be verified")
+      super
+    end
+  end
+
+  # Raised during client registration (RFC 7591) when a software statement
+  # is valid but not approved for use with this authorization server.
+  #
+  # @since 0.2.0
+  class UnapprovedSoftwareStatementError < StandardError
+    # Creates a new UnapprovedSoftwareStatementError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Software statement is not approved for use with this authorization server")
+      super
+    end
+  end
+
+  # Raised during client registration (RFC 7591) when an initial access token
+  # is required but missing or fails validation.
+  #
+  # @since 0.2.0
+  class InvalidInitialAccessTokenError < StandardError
+    # Creates a new InvalidInitialAccessTokenError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Initial access token is invalid or missing")
+      super
+    end
+  end
+
+  # Raised when a client_id URL for client metadata documents is invalid.
+  # URLs must be HTTPS, not contain fragments, and meet other security requirements.
+  #
+  # @since 0.2.0
+  class InvalidClientMetadataDocumentUrlError < StandardError
+    # Creates a new InvalidClientMetadataDocumentUrlError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Client ID URL is invalid")
+      super
+    end
+  end
+
+  # Raised when fetching a client metadata document fails due to network errors,
+  # timeouts, or HTTP error responses.
+  #
+  # @since 0.2.0
+  class ClientMetadataDocumentFetchError < StandardError
+    # Creates a new ClientMetadataDocumentFetchError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Failed to fetch client metadata document")
+      super
+    end
+  end
+
+  # Raised when a fetched client metadata document contains invalid JSON
+  # or doesn't meet the required schema.
+  #
+  # @since 0.2.0
+  class InvalidClientMetadataDocumentError < StandardError
+    # Creates a new InvalidClientMetadataDocumentError.
+    # @param msg [String] custom error message
+    def initialize(msg = "Client metadata document is invalid")
+      super
+    end
+  end
+end

data/lib/token_authority/instrumentation.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides instrumentation capabilities using ActiveSupport::Notifications.
+  #
+  # This module emits performance and timing data that APM tools (New Relic, Datadog,
+  # Skylight) can automatically capture. It can be included in classes or extended
+  # in modules to add instrumentation to methods.
+  #
+  # All events are automatically namespaced with "token_authority." prefix to avoid
+  # conflicts with other instrumentation in the application.
+  #
+  # @example Using in a module with class methods
+  #   module MyModule
+  #     extend TokenAuthority::Instrumentation
+  #
+  #     def self.process_data
+  #       instrument("process_data", record_count: 100) do |payload|
+  #         # Do work here
+  #         # Can add additional payload data: payload[:rows_processed] = 42
+  #       end
+  #     end
+  #   end
+  #
+  # @example Using in a class with instance methods
+  #   class MyClass
+  #     include TokenAuthority::Instrumentation
+  #
+  #     def process_record
+  #       instrument("process_record") do
+  #         # Do work here
+  #       end
+  #     end
+  #   end
+  #
+  # @since 0.2.0
+  module Instrumentation
+    # The namespace prefix for all instrumentation events.
+    # @return [String]
+    NAMESPACE = "token_authority"
+
+    # Wraps a block of code with instrumentation timing and error tracking.
+    #
+    # If instrumentation is disabled via configuration, the block is executed
+    # without emitting notifications. Errors are captured in the payload before
+    # being re-raised.
+    #
+    # @param event_name [String] the event name (will be prefixed with "token_authority.")
+    # @param payload [Hash] initial payload data for the event
+    #
+    # @yield [payload] the block to instrument; the payload can be modified within the block
+    # @yieldparam payload [Hash] the mutable event payload
+    #
+    # @return the result of the yielded block
+    #
+    # @raise re-raises any exception from the block after capturing it in the payload
+    #
+    # @example Basic usage
+    #   instrument("database.query", table: "users") do |payload|
+    #     result = run_query
+    #     payload[:rows] = result.count
+    #     result
+    #   end
+    #
+    # @example Error handling
+    #   instrument("risky_operation") do
+    #     raise "Something went wrong"  # Error is logged to payload before re-raising
+    #   end
+    def instrument(event_name, **payload, &block)
+      return yield(payload) unless TokenAuthority.config.instrumentation_enabled
+
+      ActiveSupport::Notifications.instrument("#{NAMESPACE}.#{event_name}", payload) do |p|
+        yield(p)
+      rescue => e
+        p[:error] = "#{e.class.name}: #{e.message}"
+        raise
+      end
+    end
+  end
+end

data/lib/token_authority/instrumentation_log_subscriber.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Subscribes to TokenAuthority instrumentation events and logs them to Rails logger.
+  #
+  # This subscriber captures all instrumentation events emitted by the TokenAuthority
+  # engine and writes them to the Rails log with timing information. This is valuable
+  # for development debugging and performance analysis.
+  #
+  # The subscriber is automatically enabled when `instrumentation_enabled` is true
+  # in the configuration. It can also be manually enabled for testing or debugging.
+  #
+  # Events are logged at INFO level with the format:
+  #   [TokenAuthority::Instrumentation] event_name (duration_ms) key1=value1 key2=value2
+  #
+  # @example Automatic subscription via configuration
+  #   TokenAuthority.configure do |config|
+  #     config.instrumentation_enabled = true
+  #   end
+  #
+  # @example Manual subscription
+  #   TokenAuthority::InstrumentationLogSubscriber.subscribe!
+  #
+  # @since 0.2.0
+  class InstrumentationLogSubscriber
+    class << self
+      # Subscribes to all TokenAuthority instrumentation events.
+      #
+      # Creates a wildcard subscription for all events matching the pattern
+      # /^token_authority\./. Each event is logged with its name, duration,
+      # and payload data.
+      #
+      # @return [ActiveSupport::Notifications::Subscription] the subscription object
+      #
+      # @note This method should only be called once during application initialization
+      #   to avoid duplicate log entries.
+      def subscribe!
+        ActiveSupport::Notifications.subscribe(/^token_authority\./) do |name, start, finish, id, payload|
+          duration_ms = (finish - start) * 1000
+          log_event(name, duration_ms, payload)
+        end
+      end
+
+      private
+
+      # Formats and logs an instrumentation event.
+      #
+      # Exceptions are excluded from the payload output to avoid cluttering logs,
+      # as they're typically logged separately by Rails' exception handling.
+      #
+      # @param name [String] the full event name (e.g., "token_authority.jwt.encode")
+      # @param duration_ms [Float] the event duration in milliseconds
+      # @param payload [Hash] the event payload data
+      #
+      # @return [void]
+      def log_event(name, duration_ms, payload)
+        payload_str = payload.except(:exception).map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+        Rails.logger.info { "[TokenAuthority::Instrumentation] #{name} (#{duration_ms.round(2)}ms) #{payload_str}" }
+      end
+    end
+  end
+end

data/lib/token_authority/json_web_token.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module TokenAuthority
+  # Provides JWT encoding and decoding functionality for TokenAuthority.
+  #
+  # This module wraps the ruby-jwt gem and adds instrumentation for monitoring.
+  # All JWTs are signed using HMAC-SHA256 with the configured secret key.
+  #
+  # Token expiration validation is disabled during decoding to allow the application
+  # to handle expired tokens gracefully and provide better error messages.
+  #
+  # @note This module uses ActiveSupport::Notifications for instrumentation when enabled.
+  #
+  # @example Encoding a token
+  #   payload = { user_id: 123, scope: "read write" }
+  #   token = TokenAuthority::JsonWebToken.encode(payload, 1.hour.from_now)
+  #
+  # @example Decoding a token
+  #   payload = TokenAuthority::JsonWebToken.decode(token)
+  #   user_id = payload[:user_id]
+  #
+  # @since 0.2.0
+  module JsonWebToken
+    extend TokenAuthority::Instrumentation
+
+    # Encodes a payload into a signed JWT.
+    #
+    # The expiration time is added to the payload before encoding.
+    # Emits an instrumentation event with the token size.
+    #
+    # @param payload [Hash] the JWT claims to encode
+    # @param expiration [Time, ActiveSupport::TimeWithZone] when the token expires
+    #   (default: 30 minutes from now)
+    #
+    # @return [String] the encoded JWT token
+    #
+    # @example
+    #   token = JsonWebToken.encode({ user_id: 42 }, 1.hour.from_now)
+    def self.encode(payload, expiration = 30.minutes.from_now)
+      payload[:exp] = expiration.to_i
+
+      instrument("jwt.encode") do |p|
+        token = JWT.encode(payload, TokenAuthority.config.secret_key)
+        p[:token_size] = token.bytesize
+        token
+      end
+    end
+
+    # Decodes and verifies a JWT signature.
+    #
+    # Expiration validation is intentionally disabled to allow the application
+    # to handle expired tokens with custom error messages and logic.
+    # Emits an instrumentation event with the token size.
+    #
+    # @param token [String] the JWT token to decode
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess] the decoded JWT claims
+    #
+    # @raise [JWT::DecodeError] if the token is malformed or signature is invalid
+    #
+    # @example
+    #   payload = JsonWebToken.decode(token_string)
+    #   user_id = payload[:user_id]
+    def self.decode(token)
+      instrument("jwt.decode", token_size: token.bytesize) do
+        (payload,) = JWT.decode(
+          token,
+          TokenAuthority.config.secret_key,
+          true,
+          {verify_expiration: false, algorithm: "HS256"}
+        )
+        ActiveSupport::HashWithIndifferentAccess.new(payload)
+      end
+    end
+  end
+end

data/lib/token_authority/log_event_subscriber.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # A Rails.event subscriber that logs TokenAuthority events to Rails.logger.
+  #
+  # This subscriber only processes events with the "token_authority." prefix,
+  # ignoring all other Rails events.
+  #
+  # Usage:
+  #   # Automatically enabled via configuration:
+  #   TokenAuthority.configure do |config|
+  #     config.event_logging_rails_logger = true
+  #   end
+  #
+  #   # Or manually subscribe:
+  #   Rails.event.subscribe(TokenAuthority::LogEventSubscriber.new)
+  #
+  class LogEventSubscriber
+    # @param event [Hash] The event hash from Rails.event
+    #   - :name [String] Event name (e.g., "token_authority.authorization.request.received")
+    #   - :payload [Hash] Event-specific data
+    #   - :context [Hash] Request-level context (request_id, user_id, etc.)
+    #   - :tags [Hash] Domain tags
+    #   - :timestamp [Integer] Nanosecond timestamp
+    #   - :source_location [Hash] File, line, and method info
+    def emit(event)
+      name = event[:name]
+
+      # Only log token_authority events
+      return unless name.start_with?("token_authority.")
+
+      payload = event[:payload] || {}
+      context = event[:context] || {}
+
+      # Format payload as key=value pairs
+      payload_str = payload.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      context_str = context.any? ? " context=#{context.inspect}" : ""
+
+      Rails.logger.info("[TokenAuthority] #{name} #{payload_str}#{context_str}")
+    end
+  end
+end

data/lib/token_authority/routing/constraints.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides routing utilities for the TokenAuthority engine.
+  #
+  # @since 0.2.0
+  module Routing
+    # Route constraint for matching the grant_type parameter in token requests.
+    #
+    # This allows routing different grant types (authorization_code, refresh_token)
+    # to different controller actions based on the request parameters.
+    #
+    # @example In routes.rb
+    #   post "token",
+    #     to: "sessions#create_from_authorization_code",
+    #     constraints: GrantTypeConstraint.new("authorization_code")
+    #
+    # @since 0.2.0
+    GrantTypeConstraint = Struct.new(:grant_type) do
+      # Determines if the request's grant_type parameter matches the constraint.
+      #
+      # @param request [ActionDispatch::Request] the Rails request object
+      # @return [Boolean] true if the grant_type parameter matches
+      def matches?(request)
+        request.request_parameters["grant_type"] == grant_type
+      end
+    end
+
+    # Route constraint for matching the token_type_hint parameter in revocation requests.
+    #
+    # This allows routing access token and refresh token revocations to different
+    # controller actions for optimized lookups.
+    #
+    # @example In routes.rb
+    #   post "revoke",
+    #     to: "sessions#revoke_access_token",
+    #     constraints: TokenTypeHintConstraint.new("access_token")
+    #
+    # @since 0.2.0
+    TokenTypeHintConstraint = Struct.new(:token_type_hint) do
+      # Determines if the request's token_type_hint parameter matches the constraint.
+      #
+      # @param request [ActionDispatch::Request] the Rails request object
+      # @return [Boolean] true if the token_type_hint parameter matches
+      def matches?(request)
+        request.request_parameters["token_type_hint"] == token_type_hint
+      end
+    end
+
+    # Route constraint that checks if dynamic client registration (RFC 7591) is enabled.
+    #
+    # This prevents registration endpoints from being accessible when the feature
+    # is disabled in configuration.
+    #
+    # @example In routes.rb
+    #   post "clients",
+    #     to: "clients#create",
+    #     constraints: DynamicRegistrationEnabledConstraint.new
+    #
+    # @since 0.2.0
+    DynamicRegistrationEnabledConstraint = Struct.new(:nothing) do
+      # Determines if dynamic client registration is enabled in the configuration.
+      #
+      # @param _request [ActionDispatch::Request] the Rails request object (unused)
+      # @return [Boolean] true if RFC 7591 dynamic registration is enabled
+      def matches?(_request)
+        TokenAuthority.config.rfc_7591_enabled
+      end
+    end
+  end
+end

data/lib/token_authority/routing/routes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActionDispatch
+  module Routing
+    class Mapper
+      ##
+      # Adds all TokenAuthority routes including OAuth 2.0 metadata endpoints
+      # (RFC 8414, RFC 9728) and mounts the TokenAuthority engine.
+      #
+      # Both RFC 8414 and RFC 9728 require the metadata endpoints to be at the
+      # root level `/.well-known/` path, not under the engine mount path.
+      #
+      # @param at [String] the path where TokenAuthority engine is mounted (default: "/oauth")
+      #
+      # @example
+      #   Rails.application.routes.draw do
+      #     token_authority_routes  # Mounts at default "/oauth"
+      #   end
+      #
+      # @example Custom mount path
+      #   Rails.application.routes.draw do
+      #     token_authority_routes(at: "/auth")
+      #   end
+      def token_authority_routes(at: "/oauth")
+        # RFC 8414: Authorization Server Metadata
+        get "/.well-known/oauth-authorization-server",
+          to: "token_authority/metadata#show",
+          defaults: {mount_path: at}
+
+        # RFC 9728: Protected Resource Metadata
+        get "/.well-known/oauth-protected-resource",
+          to: "token_authority/resource_metadata#show",
+          defaults: {mount_path: at}
+
+        mount TokenAuthority::Engine => at
+      end
+    end
+  end
+end

data/lib/token_authority/version.rb

@@ -1,3 +1,6 @@
 module TokenAuthority
-  VERSION = "0.1.0"
+  # The current version of the TokenAuthority gem.
+  #
+  # @return [String] the version string in semantic versioning format
+  VERSION = "0.2.0"
 end

data/lib/token_authority.rb

@@ -1,6 +1,35 @@
 require "token_authority/version"
 require "token_authority/engine"
+require "token_authority/configuration"
+require "token_authority/errors"
+require "token_authority/instrumentation"
+require "token_authority/json_web_token"
+require "token_authority/routing/constraints"
+require "token_authority/routing/routes"
 
+# TokenAuthority is a Rails engine that enables Rails applications to act as their own
+# OAuth 2.1 provider. It provides a complete implementation of the OAuth 2.1 authorization
+# framework with support for PKCE, JWT access tokens (RFC 9068), dynamic client registration
+# (RFC 7591), resource indicators (RFC 8707), and client metadata documents.
+#
+# The engine is designed to integrate alongside existing authentication systems (Devise,
+# custom auth, etc.) and provides mountable OAuth endpoints for authorization, token
+# exchange, and token management.
+#
+# @example Basic configuration
+#   TokenAuthority.configure do |config|
+#     config.secret_key = Rails.application.credentials.secret_key_base
+#     config.rfc_9068_audience_url = "https://api.example.com"
+#     config.rfc_9068_issuer_url = "https://example.com"
+#   end
+#
+# @since 0.2.0
 module TokenAuthority
-  # Your code goes here...
+  # Returns the table name prefix for all TokenAuthority models.
+  # This ensures that all database tables are namespaced with 'token_authority_'.
+  #
+  # @return [String] the table name prefix
+  def self.table_name_prefix
+    "token_authority_"
+  end
 end