token_authority 0.1.0 → 0.2.0

data/app/models/token_authority/access_token_request.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Models a access token request
+  class AccessTokenRequest
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include TokenAuthority::Resourceable
+    include TokenAuthority::Scopeable
+    include TokenAuthority::EventLogging
+
+    attr_accessor :code_verifier, :token_authority_authorization_grant, :redirect_uri
+
+    validate :token_authority_authorization_grant_must_be_valid
+    validate :code_verifier_must_be_valid
+    validate :redirect_uri_must_be_valid
+    validate :resources_must_be_valid
+    validate :scope_must_be_valid
+
+    # Returns the effective resources (requested or falls back to grant's resources)
+    def effective_resources
+      return resources if resources.any?
+
+      token_authority_authorization_grant&.resources || []
+    end
+
+    # Returns the effective scopes (requested or falls back to grant's scopes)
+    def effective_scopes
+      return scope if scope.present?
+
+      token_authority_authorization_grant&.scopes || []
+    end
+
+    private
+
+    def token_authority_authorization_grant_must_be_valid
+      errors.add(:token_authority_authorization_grant, :invalid) and return unless token_authority_authorization_grant_present?
+
+      errors.add(:token_authority_authorization_grant, :redeemed) if token_authority_authorization_grant.redeemed?
+    end
+
+    def code_verifier_must_be_valid
+      return unless token_authority_authorization_grant_present?
+
+      if token_authority_client.public_client_type?
+        validate_code_verifier_for_public
+      else
+        validate_code_verifier_for_confidential
+      end
+    end
+
+    def validate_code_verifier_for_public
+      debug_event("validation.pkce.started",
+        client_type: "public",
+        has_code_verifier: code_verifier.present?)
+
+      errors.add(:code_verifier, :blank) and return if code_verifier.blank?
+
+      validate_code_verifier_matches_code_challenge
+    end
+
+    def validate_code_verifier_for_confidential
+      return unless challenge_required?
+
+      debug_event("validation.pkce.started",
+        client_type: "confidential",
+        has_code_verifier: code_verifier.present?,
+        challenge_params_present: challenge_params_present_in_authorize?)
+
+      if code_verifier.blank? && challenge_params_present_in_authorize?
+        errors.add(:code_verifier, :present_in_authorize) and return
+      end
+
+      validate_code_verifier_matches_code_challenge
+    end
+
+    def challenge_required?
+      code_verifier.present? || challenge_params_present_in_authorize?
+    end
+
+    def challenge_params_present_in_authorize?
+      token_authority_authorization_grant.code_challenge.present? || token_authority_authorization_grant.code_challenge_method.present?
+    end
+
+    def validate_code_verifier_matches_code_challenge
+      challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+      valid = token_authority_authorization_grant.code_challenge == challenge
+
+      debug_event("validation.pkce.completed",
+        valid: valid,
+        code_challenge_method: token_authority_authorization_grant.code_challenge_method)
+
+      errors.add(:code_verifier, :does_not_validate_code_challenge) unless valid
+    end
+
+    def redirect_uri_must_be_valid
+      return unless token_authority_authorization_grant_present?
+
+      if token_authority_client.public_client_type?
+        validate_redirect_uri_for_public
+      else
+        validate_redirect_uri_for_confidential
+      end
+    end
+
+    def validate_redirect_uri_for_public
+      errors.add(:redirect_uri, :blank) and return if redirect_uri.blank?
+
+      validate_redirect_uri_matches_authorize_param
+    end
+
+    def validate_redirect_uri_for_confidential
+      return unless redirect_uri.present? || redirect_uri_param_present_in_authorize?
+
+      errors.add(:redirect_uri, :present_in_authorize) and return if redirect_uri.blank?
+
+      validate_redirect_uri_matches_authorize_param
+    end
+
+    def validate_redirect_uri_matches_authorize_param
+      errors.add(:redirect_uri, :mismatched) unless token_authority_authorization_grant.redirect_uri == redirect_uri
+    end
+
+    def redirect_uri_param_present_in_authorize?
+      token_authority_authorization_grant.redirect_uri.present?
+    end
+
+    def token_authority_authorization_grant_present?
+      return @token_authority_authorization_grant_present if defined?(@token_authority_authorization_grant_present)
+
+      @token_authority_authorization_grant_present = token_authority_authorization_grant&.is_a?(TokenAuthority::AuthorizationGrant)
+    end
+
+    def token_authority_client
+      @token_authority_client ||= token_authority_authorization_grant.resolved_client
+    end
+
+    def resources_must_be_valid
+      return unless token_authority_authorization_grant_present?
+      return if resources.empty?
+
+      # If resources are provided but feature is disabled, reject them
+      unless TokenAuthority.config.rfc_8707_enabled?
+        errors.add(:resources, :not_allowed)
+        return
+      end
+
+      # Validate all resource URIs
+      unless valid_resource_uris?
+        errors.add(:resources, :invalid_uri)
+        return
+      end
+
+      # Check against allowed resources list
+      unless allowed_resources?
+        errors.add(:resources, :not_allowed)
+        return
+      end
+
+      # Check that requested resources are a subset of granted resources (downscoping)
+      granted_resources = token_authority_authorization_grant.resources
+      errors.add(:resources, :not_subset) unless resources_subset_of?(granted_resources)
+    end
+
+    def scope_must_be_valid
+      return unless token_authority_authorization_grant_present?
+      return if scope.blank?
+
+      # If scopes are provided but feature is disabled, reject them
+      unless TokenAuthority.config.scopes_enabled?
+        errors.add(:scope, :not_allowed)
+        return
+      end
+
+      # Validate all scope tokens
+      unless valid_scope_tokens?
+        errors.add(:scope, :invalid)
+        return
+      end
+
+      # Check against allowed scopes list
+      unless allowed_scopes?
+        errors.add(:scope, :not_allowed)
+        return
+      end
+
+      # Check that requested scopes are a subset of granted scopes (downscoping)
+      granted_scopes = token_authority_authorization_grant.scopes || []
+      errors.add(:scope, :not_subset) unless scopes_subset_of?(granted_scopes)
+    end
+  end
+end

data/app/models/token_authority/authorization_grant.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Represents an OAuth authorization grant (authorization code).
+  #
+  # An authorization grant is created after a user consents to allow a client
+  # application access. It contains a one-time-use authorization code and PKCE
+  # challenge parameters for public clients.
+  #
+  # The grant can be associated with either:
+  # - A registered Client (stored in database)
+  # - A URL-based ClientMetadataDocument (fetched via client_id_url)
+  #
+  # Grants have a short expiration time (5 minutes by default) and can only
+  # be redeemed once. After redemption, they create a Session with access
+  # and refresh tokens.
+  #
+  # @example Redeeming a grant
+  #   session = authorization_grant.redeem(
+  #     resources: ["https://api.example.com"],
+  #     scopes: ["read", "write"]
+  #   )
+  #
+  # @since 0.2.0
+  class AuthorizationGrant < ApplicationRecord
+    include TokenAuthority::SessionCreatable
+
+    VALID_CODE_CHALLENGE_METHODS = %w[S256].freeze
+
+    belongs_to :user, class_name: TokenAuthority.config.user_class
+    belongs_to :token_authority_client, class_name: "TokenAuthority::Client", optional: true
+    has_many :token_authority_sessions,
+      class_name: "TokenAuthority::Session",
+      foreign_key: :token_authority_authorization_grant_id,
+      inverse_of: :token_authority_authorization_grant,
+      dependent: :destroy
+
+    validates :code_challenge_method, inclusion: {in: VALID_CODE_CHALLENGE_METHODS}, allow_nil: true
+    validate :must_have_client_identifier
+
+    before_validation :generate_expires_at
+    before_create :generate_public_id
+
+    # Returns the client associated with this grant.
+    #
+    # Resolves to either a registered Client or a URL-based ClientMetadataDocument
+    # depending on which association is populated. URL-based clients are fetched
+    # and cached on first access.
+    #
+    # @return [TokenAuthority::Client, TokenAuthority::ClientMetadataDocument, nil]
+    #   the client object, or nil if neither association exists
+    #
+    # @see TokenAuthority::ClientIdResolver
+    def resolved_client
+      return token_authority_client if token_authority_client.present?
+      return nil if client_id_url.blank?
+
+      @resolved_client ||= TokenAuthority::ClientIdResolver.resolve(client_id_url)
+    end
+
+    # Returns the most recent active session for this grant.
+    #
+    # After a grant is redeemed, subsequent refresh operations create new sessions
+    # with "created" status while marking old sessions as "refreshed". This method
+    # returns the current active session.
+    #
+    # @return [TokenAuthority::Session, nil] the active session, or nil if none exists
+    def active_token_authority_session
+      token_authority_sessions.created_status.order(created_at: :desc).first
+    end
+
+    # Redeems the authorization code to create a new token session.
+    #
+    # This is the final step in the authorization code flow. The grant must not
+    # have been redeemed previously, and PKCE verification (if applicable) must
+    # pass before redemption succeeds.
+    #
+    # After successful redemption, the grant is marked as redeemed and a new
+    # Session is created with access and refresh tokens.
+    #
+    # @param resources [Array<String>] resource indicators for the token session
+    # @param scopes [Array<String>] scopes for the token session
+    #
+    # @return [TokenAuthority::Session] the newly created session
+    #
+    # @raise [TokenAuthority::ServerError] if session creation fails
+    #
+    # @example
+    #   session = grant.redeem(
+    #     resources: ["https://api.example.com"],
+    #     scopes: ["read", "write"]
+    #   )
+    def redeem(resources: [], scopes: [])
+      instrument("grant.redeem") do
+        create_token_authority_session(grant: self, resources:, scopes:) do
+          update(redeemed: true)
+        end
+      end
+    rescue TokenAuthority::ServerError => error
+      raise TokenAuthority::ServerError, error.message
+    end
+
+    private
+
+    def must_have_client_identifier
+      return if token_authority_client.present? || client_id_url.present?
+
+      errors.add(:base, :must_have_client_identifier)
+    end
+
+    def generate_expires_at
+      self.expires_at ||= 5.minutes.from_now
+    end
+
+    def generate_public_id
+      self.public_id = SecureRandom.uuid
+    end
+  end
+end

data/app/models/token_authority/authorization_request.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Validates OAuth 2.1 authorization requests.
+  #
+  # This service object validates all parameters of an authorization request
+  # according to OAuth 2.1 specifications, including PKCE requirements, redirect
+  # URI validation, resource indicators (RFC 8707), and scope validation.
+  #
+  # It enforces different validation rules for public vs confidential clients:
+  # - Public clients MUST include PKCE parameters
+  # - Confidential clients MAY include PKCE parameters
+  # - Public clients MUST include redirect_uri
+  # - Confidential clients MAY omit redirect_uri if only one is registered
+  #
+  # After validation, the request can be serialized to an internal state token
+  # (JWT) for storage during the consent flow, then deserialized when processing
+  # the user's approval or denial.
+  #
+  # @example Validating an authorization request
+  #   request = AuthorizationRequest.new(
+  #     token_authority_client: client,
+  #     client_id: "abc123",
+  #     redirect_uri: "https://app.example.com/callback",
+  #     response_type: "code",
+  #     state: "xyz",
+  #     code_challenge: "E9Melhoa...",
+  #     code_challenge_method: "S256"
+  #   )
+  #   if request.valid?
+  #     # Process authorization
+  #   end
+  #
+  # @since 0.2.0
+  class AuthorizationRequest
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include TokenAuthority::Resourceable
+    include TokenAuthority::Scopeable
+
+    # Valid PKCE code challenge methods per OAuth 2.1.
+    # Only S256 (SHA-256) is supported; plain is not allowed.
+    VALID_CODE_CHALLENGE_METHODS = ["S256"].freeze
+
+    # Valid response types. Currently only "code" is supported.
+    VALID_RESPONSE_TYPES = ["code"].freeze
+
+    # @!attribute [rw] token_authority_client
+    #   The client making the authorization request.
+    #   @return [TokenAuthority::Client, TokenAuthority::ClientMetadataDocument]
+    attr_accessor :token_authority_client
+
+    # @!attribute [rw] client_id
+    #   The client identifier.
+    #   @return [String]
+    attr_accessor :client_id
+
+    # @!attribute [rw] code_challenge
+    #   The PKCE code challenge.
+    #   @return [String, nil]
+    attr_accessor :code_challenge
+
+    # @!attribute [rw] code_challenge_method
+    #   The PKCE code challenge method (S256).
+    #   @return [String, nil]
+    attr_accessor :code_challenge_method
+
+    # @!attribute [rw] redirect_uri
+    #   The URI to redirect to after authorization.
+    #   @return [String, nil]
+    attr_accessor :redirect_uri
+
+    # @!attribute [rw] response_type
+    #   The OAuth response type (code).
+    #   @return [String]
+    attr_accessor :response_type
+
+    # @!attribute [rw] state
+    #   The state parameter for CSRF protection.
+    #   @return [String, nil]
+    attr_accessor :state
+
+    validates :response_type, presence: true, inclusion: {in: VALID_RESPONSE_TYPES}
+
+    validate :token_authority_client_must_be_valid
+    validate :client_id_must_be_valid
+    validate :pkce_params_must_be_valid
+    validate :redirect_uri_must_be_valid
+    validate :resources_must_be_valid
+    validate :scope_must_be_valid
+
+    # Deserializes an authorization request from an internal state token.
+    #
+    # The state token is a JWT that preserves the authorization request parameters
+    # during the consent flow. This allows the request to survive redirects to
+    # the consent screen and back.
+    #
+    # @param token [String] the JWT state token
+    #
+    # @return [TokenAuthority::AuthorizationRequest] the deserialized request
+    #
+    # @note If the client cannot be resolved, token_authority_client will be nil
+    #   and validation will fail.
+    def self.from_internal_state_token(token)
+      attributes = TokenAuthority::JsonWebToken.decode(token)
+      token_authority_client = TokenAuthority::ClientIdResolver.resolve(attributes[:token_authority_client])
+      new(
+        **attributes.except(:token_authority_client, :exp).merge(token_authority_client:)
+      )
+    rescue TokenAuthority::ClientNotFoundError
+      new(**attributes.except(:token_authority_client, :exp).merge(token_authority_client: nil))
+    end
+
+    # Converts the authorization request to a hash for serialization.
+    #
+    # @return [Hash] the request parameters
+    def to_h
+      {
+        token_authority_client: token_authority_client.public_id,
+        client_id:,
+        state:,
+        code_challenge:,
+        code_challenge_method:,
+        redirect_uri:,
+        response_type:,
+        resources:,
+        scope:
+      }
+    end
+
+    # Serializes the authorization request to an internal state token.
+    #
+    # The state token is used to preserve authorization request parameters
+    # during the consent flow without storing them in the session.
+    #
+    # @return [String] the JWT state token
+    def to_internal_state_token
+      TokenAuthority::JsonWebToken.encode(to_h)
+    end
+
+    private
+
+    def token_authority_client_must_be_valid
+      errors.add(:token_authority_client, :invalid) unless valid_token_authority_client?
+    end
+
+    def client_id_must_be_valid
+      return unless valid_token_authority_client?
+
+      # For URL-based clients, client_id must match the URL
+      if token_authority_client.is_a?(TokenAuthority::ClientMetadataDocument)
+        errors.add(:client_id, :blank) and return if client_id.blank?
+        errors.add(:client_id, :mismatched) and return if client_id != token_authority_client.public_id
+        return
+      end
+
+      # For registered clients
+      return if token_authority_client.confidential_client_type? && client_id.blank?
+
+      errors.add(:client_id, :blank) and return if client_id.blank?
+
+      client = TokenAuthority::Client.find_by(public_id: client_id)
+      errors.add(:client_id, :unregistered_client) unless client
+    end
+
+    def pkce_params_must_be_valid
+      return unless valid_token_authority_client?
+
+      # URL-based clients are always public and must use PKCE
+      if token_authority_client.public_client_type?
+        validate_public_pkce_params
+      else
+        validate_confidential_pkce_params
+      end
+    end
+
+    def validate_public_pkce_params
+      return unless valid_token_authority_client?
+      return unless token_authority_client.public_client_type?
+
+      errors.add(:code_challenge, :required_for_public_clients) if code_challenge.blank?
+      errors.add(:code_challenge_method, :required_for_public_clients) if code_challenge_method.blank?
+      errors.add(:code_challenge_method, :invalid) unless code_challenge_method.in?(VALID_CODE_CHALLENGE_METHODS)
+    end
+
+    def validate_confidential_pkce_params
+      return unless valid_token_authority_client?
+      return unless token_authority_client.confidential_client_type?
+      return unless code_challenge.present? || code_challenge_method.present?
+
+      errors.add(:code_challenge, :required_if_other_pkce_params_present) if code_challenge.blank?
+      errors.add(:code_challenge_method, :required_if_other_pkce_params_present) if code_challenge_method.blank?
+      errors.add(:code_challenge_method, :invalid) unless code_challenge_method.in?(VALID_CODE_CHALLENGE_METHODS)
+    end
+
+    def redirect_uri_must_be_valid
+      return unless valid_token_authority_client?
+
+      if token_authority_client.public_client_type?
+        validate_public_client_redirect_uri
+      else
+        validate_confidential_client_redirect_uri
+      end
+    end
+
+    def validate_public_client_redirect_uri
+      errors.add(:redirect_uri, :blank) if redirect_uri.blank?
+      validate_redirect_uris_match
+    end
+
+    def validate_confidential_client_redirect_uri
+      return if redirect_uri.blank?
+
+      validate_redirect_uris_match
+    end
+
+    def validate_redirect_uris_match
+      errors.add(:redirect_uri, :invalid) unless token_authority_client.redirect_uri_registered?(redirect_uri)
+    end
+
+    def valid_token_authority_client?
+      token_authority_client.is_a?(TokenAuthority::Client) ||
+        token_authority_client.is_a?(TokenAuthority::ClientMetadataDocument)
+    end
+
+    def resources_must_be_valid
+      # Check if resource is required
+      if TokenAuthority.config.rfc_8707_require_resource && resources.empty?
+        errors.add(:resources, :required)
+        return
+      end
+
+      return if resources.empty?
+
+      # If resources are provided but feature is disabled, reject them
+      unless TokenAuthority.config.rfc_8707_enabled?
+        errors.add(:resources, :not_allowed)
+        return
+      end
+
+      # Validate all resource URIs
+      unless valid_resource_uris?
+        errors.add(:resources, :invalid_uri)
+        return
+      end
+
+      # Check against allowed resources list
+      errors.add(:resources, :not_allowed) unless allowed_resources?
+    end
+
+    def scope_must_be_valid
+      # Check if scope is required
+      if TokenAuthority.config.require_scope && scope.blank?
+        errors.add(:scope, :required)
+        return
+      end
+
+      return if scope.blank?
+
+      # If scopes are provided but feature is disabled, reject them
+      unless TokenAuthority.config.scopes_enabled?
+        errors.add(:scope, :not_allowed)
+        return
+      end
+
+      # Validate all scope tokens
+      unless valid_scope_tokens?
+        errors.add(:scope, :invalid)
+        return
+      end
+
+      # Check against allowed scopes list
+      errors.add(:scope, :not_allowed) unless allowed_scopes?
+    end
+  end
+end

data/app/models/token_authority/authorization_server_metadata.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Builds OAuth 2.0 Authorization Server Metadata per RFC 8414.
+  #
+  # This class generates the metadata document that clients use to discover
+  # the authorization server's capabilities and endpoint locations. The metadata
+  # is typically served at /.well-known/oauth-authorization-server.
+  #
+  # The metadata includes:
+  # - Endpoint URLs (authorization, token, revocation, registration)
+  # - Supported grant types and response types
+  # - Supported token endpoint authentication methods
+  # - PKCE code challenge methods
+  # - Optional scopes and service documentation
+  #
+  # @example Building metadata
+  #   metadata = AuthorizationServerMetadata.new(mount_path: "/oauth")
+  #   metadata.to_h
+  #   # => {
+  #   #   issuer: "https://example.com",
+  #   #   authorization_endpoint: "https://example.com/oauth/authorize",
+  #   #   ...
+  #   # }
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc8414.html RFC 8414: OAuth 2.0 Authorization Server Metadata
+  # @since 0.2.0
+  class AuthorizationServerMetadata
+    # Creates a new metadata builder.
+    #
+    # @param mount_path [String] the path where the OAuth engine is mounted
+    #   (e.g., "/oauth")
+    def initialize(mount_path:)
+      @mount_path = mount_path
+    end
+
+    # Converts the metadata to a hash for JSON serialization.
+    #
+    # Builds the complete metadata document including all required and optional
+    # fields based on the current configuration. The registration_endpoint is
+    # only included when dynamic client registration is enabled.
+    #
+    # @return [Hash] the authorization server metadata
+    #
+    # @example
+    #   metadata = AuthorizationServerMetadata.new(mount_path: "/oauth")
+    #   json = metadata.to_h.to_json
+    def to_h
+      metadata = {
+        issuer: issuer,
+        authorization_endpoint: "#{issuer}#{@mount_path}/authorize",
+        token_endpoint: "#{issuer}#{@mount_path}/token",
+        revocation_endpoint: "#{issuer}#{@mount_path}/revoke",
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
+        code_challenge_methods_supported: ["S256"]
+      }
+
+      metadata[:scopes_supported] = scopes_supported if scopes_supported.any?
+      metadata[:service_documentation] = service_documentation if service_documentation.present?
+
+      # RFC 7591 Dynamic Client Registration
+      if TokenAuthority.config.rfc_7591_enabled
+        metadata[:registration_endpoint] = "#{issuer}#{@mount_path}/register"
+      end
+
+      metadata
+    end
+
+    private
+
+    # Returns the issuer URL from configuration with trailing slashes removed.
+    # @return [String]
+    # @api private
+    def issuer
+      TokenAuthority.config.rfc_9068_issuer_url.to_s.chomp("/")
+    end
+
+    # Returns the list of supported scopes from configuration.
+    # @return [Array<String>]
+    # @api private
+    def scopes_supported
+      TokenAuthority.config.scopes&.keys || []
+    end
+
+    # Returns the service documentation URL from configuration.
+    # @return [String, nil]
+    # @api private
+    def service_documentation
+      TokenAuthority.config.rfc_8414_service_documentation
+    end
+
+    # Returns the supported token endpoint authentication methods.
+    # @return [Array<String>]
+    # @api private
+    def token_endpoint_auth_methods_supported
+      TokenAuthority.config.rfc_7591_allowed_token_endpoint_auth_methods
+    end
+  end
+end