token_authority 0.1.0 → 0.2.0

data/app/models/concerns/token_authority/claim_validatable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides JWT claim validation for token models.
+  #
+  # This concern adds ActiveModel validation for standard JWT claims (aud, exp, iat,
+  # iss, jti) and integrates with the Session model to automatically update session
+  # status when tokens fail validation.
+  #
+  # When validation fails for revocable claims (aud, iss, user_id), the associated
+  # session is marked as revoked. When validation fails for expirable claims (exp),
+  # the session is marked as expired.
+  #
+  # @example Including in a token model
+  #   class MyToken
+  #     include TokenAuthority::ClaimValidatable
+  #   end
+  #
+  # @since 0.2.0
+  module ClaimValidatable
+    extend ActiveSupport::Concern
+
+    # JWT claims that should trigger session revocation when invalid.
+    # These represent security violations like wrong audience or issuer.
+    REVOCABLE_CLAIMS = %i[aud iss user_id].freeze
+
+    # JWT claims that should trigger session expiration when invalid.
+    # Currently only includes the exp (expiration time) claim.
+    EXPIRABLE_CLAIMS = %i[exp].freeze
+
+    included do
+      include ActiveModel::Model
+      include ActiveModel::Validations
+      include ActiveModel::Validations::Callbacks
+
+      attr_accessor :aud, :exp, :iat, :iss, :jti
+
+      validates :jti, presence: true
+
+      validates :aud, presence: true, format: {with: /\A#{TokenAuthority.config.rfc_9068_audience_url}*/}
+
+      validates :exp, presence: true
+      validate do
+        next if exp.blank?
+
+        errors.add(:exp, :expired) if Time.zone.now > Time.zone.at(exp)
+      end
+
+      validates :iss, presence: true, format: {with: /\A#{TokenAuthority.config.rfc_9068_issuer_url}\z/}
+
+      after_validation :expire_token_authority_session, if: :errors_for_expirable_claims?
+      after_validation :revoke_token_authority_session, if: :errors_for_revocable_claims?
+    end
+
+    private
+
+    def token_authority_session
+      return @token_authority_session if defined?(@token_authority_session)
+
+      @token_authority_session = TokenAuthority::Session.find_by(query_params_for_token_authority_session)
+    end
+
+    def query_params_for_token_authority_session
+      {key_for_jti_query => jti}
+    end
+
+    def key_for_jti_query
+      :"#{self.class.name.demodulize.underscore}_jti"
+    end
+
+    def errors_for_revocable_claims?
+      return false if skip_token_authority_session_update?
+
+      errors.attribute_names.intersect?(REVOCABLE_CLAIMS)
+    end
+
+    def revoke_token_authority_session
+      token_authority_session.update(status: "revoked")
+    end
+
+    def errors_for_expirable_claims?
+      return false if skip_token_authority_session_update?
+
+      errors.attribute_names.intersect?(EXPIRABLE_CLAIMS)
+    end
+
+    def expire_token_authority_session
+      token_authority_session.update(status: "expired")
+    end
+
+    def skip_token_authority_session_update?
+      errors.blank? || errors.include?(:jti)
+    end
+  end
+end

data/app/models/concerns/token_authority/event_logging.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides structured event logging for model classes.
+  #
+  # This concern integrates with Rails 8.1+ event logging (Rails.event) to emit
+  # structured, machine-readable events for security auditing, monitoring, and debugging.
+  # All events are automatically namespaced and timestamped.
+  #
+  # Two event levels are supported:
+  # - Production events (notify_event): Always emitted when event_logging_enabled is true
+  # - Debug events (debug_event): Only emitted when both event_logging_enabled and
+  #   event_logging_debug_events are true
+  #
+  # Events can be consumed by Rails event subscribers for logging, metrics, or
+  # integration with external monitoring systems.
+  #
+  # @example Using in a model
+  #   class Session < ApplicationRecord
+  #     include TokenAuthority::EventLogging
+  #
+  #     def revoke
+  #       notify_event("security.session.revoked",
+  #         session_id: id,
+  #         client_id: client.public_id,
+  #         reason: "user_logout")
+  #     end
+  #   end
+  #
+  # @example Using debug events
+  #   debug_event("validation.pkce.started",
+  #     code_challenge: challenge,
+  #     challenge_method: "S256")
+  #
+  # @since 0.2.0
+  module EventLogging
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_event_logging_enabled, default: true
+    end
+
+    class_methods do
+      # Emits a production-level event.
+      #
+      # Events are namespaced with "token_authority." and include a timestamp.
+      # Only emitted when event logging is enabled in configuration.
+      #
+      # @param event_name [String] the event name (will be prefixed)
+      # @param request_id [String, nil] optional request ID for correlation
+      # @param payload [Hash] additional event data
+      #
+      # @return [void]
+      #
+      # @example
+      #   notify_event("client.lookup.completed",
+      #     client_id: "abc123",
+      #     lookup_duration_ms: 42)
+      def notify_event(event_name, request_id: nil, **payload)
+        return unless event_logging_enabled?
+
+        full_payload = build_payload(payload, request_id: request_id)
+        Rails.event.notify("token_authority.#{event_name}", **full_payload)
+      end
+
+      # Emits a debug-level event.
+      #
+      # Debug events are only emitted when both event_logging_enabled and
+      # event_logging_debug_events are true in configuration. Use for verbose
+      # logging that aids in troubleshooting but would be too noisy in production.
+      #
+      # @param event_name [String] the event name (will be prefixed)
+      # @param request_id [String, nil] optional request ID for correlation
+      # @param payload [Hash] additional event data
+      #
+      # @return [void]
+      #
+      # @example
+      #   debug_event("validation.pkce.challenge_computed",
+      #     code_verifier_length: 128,
+      #     challenge_method: "S256")
+      def debug_event(event_name, request_id: nil, **payload)
+        return unless event_logging_enabled?
+        return unless debug_events_enabled?
+
+        full_payload = build_payload(payload, request_id: request_id)
+        Rails.event.debug("token_authority.#{event_name}", **full_payload)
+      end
+
+      private
+
+      # Checks if event logging is enabled.
+      # @return [Boolean]
+      # @api private
+      def event_logging_enabled?
+        _event_logging_enabled && TokenAuthority.config.event_logging_enabled
+      end
+
+      # Checks if debug events are enabled.
+      # @return [Boolean]
+      # @api private
+      def debug_events_enabled?
+        TokenAuthority.config.event_logging_debug_events
+      end
+
+      # Builds the complete event payload with timestamp and optional request_id.
+      # @param payload [Hash] the base payload
+      # @param request_id [String, nil] optional request ID
+      # @return [Hash] the enriched payload
+      # @api private
+      def build_payload(payload, request_id: nil)
+        base = {timestamp: Time.current.iso8601(6)}
+        base[:request_id] = request_id if request_id.present?
+        base.merge(payload)
+      end
+    end
+
+    # Emits a production-level event from instance methods.
+    #
+    # Delegates to the class method. See class method documentation for details.
+    #
+    # @param event_name [String] the event name (will be prefixed)
+    # @param request_id [String, nil] optional request ID for correlation
+    # @param payload [Hash] additional event data
+    #
+    # @return [void]
+    def notify_event(event_name, request_id: nil, **payload)
+      self.class.notify_event(event_name, request_id: request_id, **payload)
+    end
+
+    # Emits a debug-level event from instance methods.
+    #
+    # Delegates to the class method. See class method documentation for details.
+    #
+    # @param event_name [String] the event name (will be prefixed)
+    # @param request_id [String, nil] optional request ID for correlation
+    # @param payload [Hash] additional event data
+    #
+    # @return [void]
+    def debug_event(event_name, request_id: nil, **payload)
+      self.class.debug_event(event_name, request_id: request_id, **payload)
+    end
+  end
+end

data/app/models/concerns/token_authority/resourceable.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides RFC 8707 resource indicator handling for authorization requests and tokens.
+  #
+  # Resource indicators allow clients to specify which protected resources (APIs)
+  # they want access to. This concern handles validation of resource URIs according
+  # to RFC 8707 requirements and checking resources against the configured allowed
+  # resource list.
+  #
+  # Resource URIs must:
+  # - Be absolute URIs with http or https scheme
+  # - Include a host
+  # - Not contain a fragment
+  #
+  # @example Using in a model
+  #   class AuthorizationRequest
+  #     include TokenAuthority::Resourceable
+  #   end
+  #
+  #   request.resources = ["https://api.example.com", "https://files.example.com"]
+  #   request.resources # => ["https://api.example.com", "https://files.example.com"]
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc8707.html RFC 8707: Resource Indicators for OAuth 2.0
+  # @since 0.2.0
+  module Resourceable
+    extend ActiveSupport::Concern
+
+    # Returns the resource indicators as an array.
+    #
+    # @return [Array<String>] the resource URIs
+    def resources
+      @resources ||= []
+    end
+
+    # Sets the resource indicators from an array or array-like value.
+    #
+    # Nil or empty values result in an empty array.
+    #
+    # @param value [Array<String>, String, nil] the resource URIs to set
+    #
+    # @example
+    #   obj.resources = ["https://api.example.com"]
+    #   obj.resources # => ["https://api.example.com"]
+    def resources=(value)
+      @resources = Array(value).presence || []
+    end
+
+    private
+
+    # Validates that a single resource URI meets RFC 8707 requirements.
+    #
+    # @param uri [String] the resource URI to validate
+    #
+    # @return [Boolean] true if the URI is valid
+    # @api private
+    def valid_resource_uri?(uri)
+      return false if uri.blank?
+
+      parsed_uri = URI.parse(uri)
+
+      # Must be absolute URI with http/https scheme
+      return false unless parsed_uri.is_a?(URI::HTTP) || parsed_uri.is_a?(URI::HTTPS)
+
+      # Must not have a fragment
+      return false if parsed_uri.fragment.present?
+
+      # Must have a host
+      return false if parsed_uri.host.blank?
+
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Validates that all resource URIs meet RFC 8707 requirements.
+    #
+    # @return [Boolean] true if all URIs are valid
+    # @api private
+    def valid_resource_uris?
+      resources.all? { |uri| valid_resource_uri?(uri) }
+    end
+
+    # Checks if all requested resources are in the allowed resources list.
+    #
+    # Returns true if resource indicators are not enabled in configuration.
+    #
+    # @return [Boolean] true if all resources are allowed
+    # @api private
+    def allowed_resources?
+      return true unless TokenAuthority.config.rfc_8707_enabled?
+
+      resources.all? { |uri| TokenAuthority.config.rfc_8707_resources.key?(uri) }
+    end
+
+    # Checks if the current resources are a subset of the granted resources.
+    #
+    # Used during token refresh to ensure the new token doesn't request
+    # access to more resources than the original grant.
+    #
+    # @param granted [Array<String>, nil] the originally granted resources
+    #
+    # @return [Boolean] true if resources are a subset of granted resources
+    # @api private
+    def resources_subset_of?(granted)
+      return true if granted.blank? || resources.blank?
+
+      (resources - granted).empty?
+    end
+  end
+end

data/app/models/concerns/token_authority/scopeable.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides OAuth scope handling for authorization requests and tokens.
+  #
+  # This concern handles parsing space-delimited scope strings per OAuth 2.1,
+  # validation of scope tokens per RFC 6749, and checking scopes against the
+  # configured allowed scopes.
+  #
+  # Scopes are stored internally as arrays but can be set from either strings
+  # or arrays. The scope setter automatically splits space-delimited strings
+  # into individual scope tokens.
+  #
+  # @example Using in a model
+  #   class AuthorizationRequest
+  #     include TokenAuthority::Scopeable
+  #   end
+  #
+  #   request.scope = "read write admin"
+  #   request.scope # => ["read", "write", "admin"]
+  #   request.scope_as_string # => "read write admin"
+  #
+  # @since 0.2.0
+  module Scopeable
+    extend ActiveSupport::Concern
+
+    # Regular expression for valid scope tokens per RFC 6749 Section 3.3.
+    # Scope tokens must not contain whitespace, double quotes, or backslashes.
+    # Allowed characters are printable ASCII excluding space, double-quote, and backslash.
+    VALID_SCOPE_TOKEN = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/
+
+    # Returns the scopes as an array.
+    #
+    # @return [Array<String>] the scope tokens
+    def scope
+      @scope ||= []
+    end
+
+    # Sets the scopes from a string or array.
+    #
+    # String values are split on whitespace into individual tokens.
+    # Array values are used directly. Other values result in an empty array.
+    #
+    # @param value [String, Array<String>, nil] the scopes to set
+    #
+    # @example Setting from a string
+    #   obj.scope = "read write"
+    #   obj.scope # => ["read", "write"]
+    #
+    # @example Setting from an array
+    #   obj.scope = ["read", "write"]
+    #   obj.scope # => ["read", "write"]
+    def scope=(value)
+      @scope = case value
+      when String then value.split(/\s+/).reject(&:blank?)
+      when Array then value
+      else []
+      end
+    end
+
+    # Returns the scopes as a space-delimited string.
+    #
+    # This format is used in OAuth responses and JWT scope claims.
+    #
+    # @return [String] space-delimited scope string
+    def scope_as_string
+      scope.join(" ")
+    end
+
+    private
+
+    # Validates that all scope tokens match the RFC 6749 format.
+    #
+    # @return [Boolean] true if all tokens are valid
+    # @api private
+    def valid_scope_tokens?
+      scope.all? { |s| VALID_SCOPE_TOKEN.match?(s) }
+    end
+
+    # Checks if all requested scopes are in the allowed scopes list.
+    #
+    # Returns true if scopes are not enabled in configuration.
+    #
+    # @return [Boolean] true if all scopes are allowed
+    # @api private
+    def allowed_scopes?
+      return true unless TokenAuthority.config.scopes_enabled?
+      scope.all? { |s| TokenAuthority.config.scopes.key?(s) }
+    end
+
+    # Checks if the current scopes are a subset of the granted scopes.
+    #
+    # Used during token refresh to ensure the new token doesn't request
+    # more privileges than the original grant.
+    #
+    # @param granted [Array<String>, nil] the originally granted scopes
+    #
+    # @return [Boolean] true if scopes are a subset of granted scopes
+    # @api private
+    def scopes_subset_of?(granted)
+      return true if granted.blank? || scope.blank?
+      (scope - Array(granted)).empty?
+    end
+  end
+end

data/app/models/concerns/token_authority/session_creatable.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Provides session creation functionality for authorization grants and token refreshes.
+  #
+  # This concern encapsulates the complex logic of creating a new OAuth session with
+  # access and refresh token pairs. It handles:
+  # - Generating access and refresh tokens with appropriate lifetimes
+  # - Creating the session record with JTI references
+  # - Yielding to allow the caller to update related records (e.g., marking grant as redeemed)
+  # - Returning a TokenContainer with all token data
+  #
+  # Used by both AuthorizationGrant (when redeeming) and Session (when refreshing).
+  #
+  # @example In a model
+  #   class AuthorizationGrant < ApplicationRecord
+  #     include TokenAuthority::SessionCreatable
+  #
+  #     def redeem(resources: [], scopes: [])
+  #       create_token_authority_session(grant: self, resources:, scopes:) do
+  #         update(redeemed: true)
+  #       end
+  #     end
+  #   end
+  #
+  # @since 0.2.0
+  module SessionCreatable
+    extend ActiveSupport::Concern
+    include TokenAuthority::Instrumentation
+
+    # Container for token response data.
+    #
+    # @!attribute [r] access_token
+    #   The encoded JWT access token string.
+    #   @return [String]
+    #
+    # @!attribute [r] refresh_token
+    #   The encoded JWT refresh token string.
+    #   @return [String]
+    #
+    # @!attribute [r] expiration
+    #   The Unix timestamp when the access token expires.
+    #   @return [Integer]
+    #
+    # @!attribute [r] scope
+    #   Space-delimited scope string, or nil if no scopes.
+    #   @return [String, nil]
+    #
+    # @!attribute [r] token_authority_session
+    #   The created Session record.
+    #   @return [TokenAuthority::Session]
+    TokenContainer = Data.define(:access_token, :refresh_token, :expiration, :scope, :token_authority_session)
+
+    private
+
+    # Creates a new token session with access and refresh tokens.
+    #
+    # Generates token pairs based on the client's configured lifetimes, creates
+    # a Session record, and yields to allow the caller to perform additional
+    # actions (like marking a grant as redeemed).
+    #
+    # Emits instrumentation events for monitoring session creation performance.
+    #
+    # @param grant [TokenAuthority::AuthorizationGrant] the authorization grant
+    # @param resources [Array<String>] resource indicators for the tokens
+    # @param scopes [Array<String>] scope tokens for the tokens
+    #
+    # @yield allows the caller to update related records within the session creation
+    #
+    # @return [TokenContainer] container with access_token, refresh_token, expiration,
+    #   scope, and token_authority_session
+    #
+    # @raise [TokenAuthority::ServerError] if session creation fails validation
+    #
+    # @api private
+    def create_token_authority_session(grant:, resources: [], scopes: [])
+      client = grant.resolved_client
+
+      instrument("session.create") do
+        access_token_expiration = client.access_token_duration.seconds.from_now.to_i
+        access_token = TokenAuthority::AccessToken.default(user_id:, exp: access_token_expiration, resources:, scopes:)
+
+        refresh_token_expiration = client.refresh_token_duration.seconds.from_now.to_i
+        refresh_token = TokenAuthority::RefreshToken.default(exp: refresh_token_expiration, resources:, scopes:)
+
+        token_authority_session = grant.token_authority_sessions.new(
+          access_token_jti: access_token.jti, refresh_token_jti: refresh_token.jti
+        )
+
+        if token_authority_session.save
+          yield
+          scope = scopes.any? ? scopes.join(" ") : nil
+          TokenContainer[access_token.to_encoded_token, refresh_token.to_encoded_token, access_token.exp, scope, token_authority_session]
+        else
+          errors = token_authority_session.errors.full_messages.join(", ")
+          raise TokenAuthority::ServerError, I18n.t("token_authority.errors.oauth_session_failure", errors:)
+        end
+      end
+    end
+  end
+end

data/app/models/token_authority/access_token.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Represents an OAuth 2.1 access token with JWT format per RFC 9068.
+  #
+  # Access tokens are short-lived bearer tokens that grant access to protected
+  # resources. They are not persisted in the database; instead, only their JTI
+  # (JWT ID) is stored in the Session model for revocation lookups.
+  #
+  # The tokens follow RFC 9068 JWT Profile for OAuth Access Tokens, including
+  # standard claims (iss, aud, exp, iat, jti) plus custom claims like user_id
+  # and scope.
+  #
+  # This is an ActiveModel object (not ActiveRecord) that provides validation
+  # and serialization of JWT claims without database persistence.
+  #
+  # @example Creating a new access token
+  #   token = TokenAuthority::AccessToken.default(
+  #     exp: 5.minutes.from_now,
+  #     user_id: 42,
+  #     resources: ["https://api.example.com"],
+  #     scopes: ["read", "write"]
+  #   )
+  #   jwt_string = token.to_encoded_token
+  #
+  # @example Decoding and validating a token
+  #   token = TokenAuthority::AccessToken.from_token(jwt_string)
+  #   token.valid? # => true/false
+  #
+  # @since 0.2.0
+  class AccessToken
+    include TokenAuthority::ClaimValidatable
+
+    # @!attribute [rw] user_id
+    #   The ID of the user this token grants access for.
+    #   @return [Integer]
+    attr_accessor :user_id
+
+    # @!attribute [rw] scope
+    #   Space-separated list of OAuth scopes granted to this token.
+    #   @return [String, nil]
+    attr_accessor :scope
+
+    validates :user_id, presence: true, comparison: {equal_to: :user_id_from_token_authority_session}
+
+    # Creates a new access token with default claims per RFC 9068.
+    #
+    # The audience (aud) claim is set from resource indicators if provided,
+    # otherwise falls back to the configured default audience URL.
+    #
+    # @param exp [Time, Integer] token expiration time
+    # @param user_id [Integer] the user ID
+    # @param resources [Array<String>] resource indicators (RFC 8707)
+    # @param scopes [Array<String>] OAuth scopes to include
+    #
+    # @return [TokenAuthority::AccessToken] the new token instance
+    #
+    # @example
+    #   token = AccessToken.default(
+    #     exp: 5.minutes.from_now,
+    #     user_id: 123,
+    #     resources: ["https://api.example.com"],
+    #     scopes: ["read", "write"]
+    #   )
+    def self.default(exp:, user_id:, resources: [], scopes: [])
+      # Use resources for aud claim if provided, otherwise fall back to config
+      aud = if resources.any?
+        (resources.size == 1) ? resources.first : resources
+      else
+        TokenAuthority.config.rfc_9068_audience_url
+      end
+
+      scope_claim = scopes.any? ? scopes.join(" ") : nil
+
+      new(
+        aud:,
+        exp:,
+        iat: Time.zone.now.to_i,
+        iss: TokenAuthority.config.rfc_9068_issuer_url,
+        jti: SecureRandom.uuid,
+        user_id:,
+        scope: scope_claim
+      )
+    end
+
+    # Decodes a JWT string into an AccessToken instance.
+    #
+    # @param token [String] the JWT-encoded access token
+    #
+    # @return [TokenAuthority::AccessToken] the decoded token instance
+    #
+    # @raise [JWT::DecodeError] if the token is malformed or signature is invalid
+    #
+    # @example
+    #   token = AccessToken.from_token(jwt_string)
+    #   user_id = token.user_id
+    def self.from_token(token)
+      new(TokenAuthority::JsonWebToken.decode(token))
+    end
+
+    # Converts the token to a hash of JWT claims.
+    #
+    # Nil values are omitted from the hash to produce a minimal JWT payload.
+    #
+    # @return [Hash] the JWT claims
+    def to_h
+      {aud:, exp:, iat:, iss:, jti:, user_id:, scope:}.compact
+    end
+
+    # Encodes the token as a signed JWT string.
+    #
+    # @return [String] the JWT-encoded access token
+    def to_encoded_token
+      TokenAuthority::JsonWebToken.encode(to_h, exp)
+    end
+
+    private
+
+    # Returns the user_id from the associated session for validation.
+    #
+    # @return [Integer, nil]
+    # @api private
+    def user_id_from_token_authority_session
+      token_authority_session&.user_id
+    end
+  end
+end