token_authority 0.1.0 → 0.2.0

data/app/models/token_authority/protected_resource_metadata.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Builds the RFC 9728 OAuth 2.0 Protected Resource Metadata response
+  class ProtectedResourceMetadata
+    def initialize(mount_path:)
+      @mount_path = mount_path
+    end
+
+    def to_h
+      metadata = {
+        resource: resource,
+        authorization_servers: authorization_servers
+      }
+
+      metadata[:scopes_supported] = scopes_supported if scopes_supported.any?
+      metadata[:bearer_methods_supported] = bearer_methods_supported if bearer_methods_supported.present?
+      metadata[:jwks_uri] = jwks_uri if jwks_uri.present?
+      metadata[:resource_name] = resource_name if resource_name.present?
+      metadata[:resource_documentation] = resource_documentation if resource_documentation.present?
+      metadata[:resource_policy_uri] = resource_policy_uri if resource_policy_uri.present?
+      metadata[:resource_tos_uri] = resource_tos_uri if resource_tos_uri.present?
+
+      metadata
+    end
+
+    private
+
+    def config
+      TokenAuthority.config
+    end
+
+    def issuer
+      config.rfc_9068_issuer_url.to_s.chomp("/")
+    end
+
+    def resource
+      config.rfc_9728_resource.presence || issuer
+    end
+
+    def authorization_servers
+      config.rfc_9728_authorization_servers.presence || [issuer]
+    end
+
+    def scopes_supported
+      config.rfc_9728_scopes_supported.presence || config.scopes&.keys || []
+    end
+
+    def bearer_methods_supported
+      config.rfc_9728_bearer_methods_supported
+    end
+
+    def jwks_uri
+      config.rfc_9728_jwks_uri
+    end
+
+    def resource_name
+      config.rfc_9728_resource_name
+    end
+
+    def resource_documentation
+      config.rfc_9728_resource_documentation
+    end
+
+    def resource_policy_uri
+      config.rfc_9728_resource_policy_uri
+    end
+
+    def resource_tos_uri
+      config.rfc_9728_resource_tos_uri
+    end
+  end
+end

data/app/models/token_authority/refresh_token.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Represents an OAuth 2.1 refresh token with JWT format.
+  #
+  # Refresh tokens are long-lived tokens used to obtain new access tokens without
+  # requiring user interaction. Like access tokens, they follow JWT format but have
+  # a longer expiration time (default: 14 days).
+  #
+  # Refresh tokens implement token rotation: each refresh operation creates a new
+  # session with new access and refresh tokens, and marks the old session as
+  # "refreshed". This prevents replay attacks.
+  #
+  # Unlike access tokens, refresh tokens do not include a user_id claim since they
+  # are looked up by JTI in the Session table which already has the user association.
+  #
+  # This is an ActiveModel object (not ActiveRecord) that provides validation
+  # and serialization of JWT claims without database persistence.
+  #
+  # @example Creating a refresh token
+  #   token = TokenAuthority::RefreshToken.default(
+  #     exp: 14.days.from_now,
+  #     resources: ["https://api.example.com"],
+  #     scopes: ["read", "write"]
+  #   )
+  #   jwt_string = token.to_encoded_token
+  #
+  # @example Decoding a refresh token
+  #   token = TokenAuthority::RefreshToken.from_token(jwt_string)
+  #   token.valid? # => true/false
+  #
+  # @since 0.2.0
+  class RefreshToken
+    include TokenAuthority::ClaimValidatable
+
+    # @!attribute [rw] scope
+    #   Space-separated list of OAuth scopes for this refresh token.
+    #   @return [String, nil]
+    attr_accessor :scope
+
+    # Creates a new refresh token with standard JWT claims.
+    #
+    # 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 resources [Array<String>] resource indicators (RFC 8707)
+    # @param scopes [Array<String>] OAuth scopes to include
+    #
+    # @return [TokenAuthority::RefreshToken] the new token instance
+    #
+    # @example
+    #   token = RefreshToken.default(
+    #     exp: 14.days.from_now,
+    #     resources: ["https://api.example.com"],
+    #     scopes: ["read", "write"]
+    #   )
+    def self.default(exp:, 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
+
+      # Only include scope if scopes are provided
+      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,
+        scope: scope_claim
+      )
+    end
+
+    # Decodes a JWT string into a RefreshToken instance.
+    #
+    # @param token [String] the JWT-encoded refresh token
+    #
+    # @return [TokenAuthority::RefreshToken] the decoded token instance
+    #
+    # @raise [JWT::DecodeError] if the token is malformed or signature is invalid
+    #
+    # @example
+    #   token = RefreshToken.from_token(jwt_string)
+    #   jti = token.jti
+    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:, scope:}.compact
+    end
+
+    # Encodes the token as a signed JWT string.
+    #
+    # @return [String] the JWT-encoded refresh token
+    def to_encoded_token
+      TokenAuthority::JsonWebToken.encode(to_h, exp)
+    end
+  end
+end

data/app/models/token_authority/refresh_token_request.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Models a refresh token request
+  class RefreshTokenRequest
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include TokenAuthority::Resourceable
+    include TokenAuthority::Scopeable
+
+    attr_accessor :token, :client_id
+
+    validate :token_authority_session_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
+
+    # Returns the session for use in refresh operation
+    def token_authority_session
+      return nil unless token
+
+      @token_authority_session ||= TokenAuthority::Session.find_by(refresh_token_jti: token.jti)
+    end
+
+    # Returns the resolved client_id (from param or from grant's client)
+    def resolved_client_id
+      client_id.presence || token_authority_session&.token_authority_authorization_grant&.resolved_client&.public_id
+    end
+
+    private
+
+    def token_authority_session_must_be_valid
+      errors.add(:token, :blank) and return if token.blank?
+
+      errors.add(:token, :session_not_found) if token_authority_session.nil?
+    end
+
+    def token_authority_authorization_grant
+      @token_authority_authorization_grant ||= token_authority_session&.token_authority_authorization_grant
+    end
+
+    def resources_must_be_valid
+      return unless token_authority_session_valid?
+      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_session_valid?
+      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
+
+    def token_authority_session_valid?
+      return @token_authority_session_valid if defined?(@token_authority_session_valid)
+
+      @token_authority_session_valid = token_authority_session.present?
+    end
+  end
+end

data/app/models/token_authority/session.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Represents an OAuth token session containing access and refresh tokens.
+  #
+  # Sessions track the lifecycle of token pairs from creation through expiration,
+  # refresh, or revocation. They implement refresh token rotation (each refresh
+  # creates a new session) and revocation detection to prevent replay attacks.
+  #
+  # The session stores JWT identifiers (jti claims) for both access and refresh
+  # tokens, but not the tokens themselves. This allows efficient revocation lookups
+  # without storing the full JWT payloads.
+  #
+  # Session status transitions:
+  # - created: Active session with valid tokens
+  # - refreshed: Old session that was replaced by a refresh operation
+  # - expired: Session that exceeded its lifetime (future use)
+  # - revoked: Session that was explicitly revoked or detected as compromised
+  #
+  # @example Refreshing a session
+  #   new_session = session.refresh(
+  #     token: refresh_token,
+  #     client_id: client.public_id,
+  #     resources: ["https://api.example.com"]
+  #   )
+  #
+  # @example Revoking a session
+  #   session.revoke_self_and_active_session(
+  #     reason: "user_logout",
+  #     request_id: "req-123"
+  #   )
+  #
+  # @since 0.2.0
+  class Session < ApplicationRecord
+    include TokenAuthority::SessionCreatable
+    include TokenAuthority::EventLogging
+
+    STATUS_ENUM_VALUES = {
+      created: "created",
+      expired: "expired",
+      refreshed: "refreshed",
+      revoked: "revoked"
+    }.freeze
+
+    VALID_UUID_REGEX = /[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}/i
+
+    belongs_to :token_authority_authorization_grant, class_name: "TokenAuthority::AuthorizationGrant"
+
+    enum :status, STATUS_ENUM_VALUES, suffix: true
+
+    delegate :user_id, to: :token_authority_authorization_grant
+
+    validates :access_token_jti, presence: true, uniqueness: true, format: {with: VALID_UUID_REGEX}
+    validates :refresh_token_jti, presence: true, uniqueness: true, format: {with: VALID_UUID_REGEX}
+
+    # Refreshes the session by creating a new session with rotated tokens.
+    #
+    # This implements refresh token rotation as recommended by OAuth 2.1.
+    # The current session is marked as "refreshed" and a new session is created
+    # with new access and refresh tokens.
+    #
+    # Includes replay attack detection: if the session is not in "created" status
+    # or the client_id doesn't match, the refresh token has been stolen or reused.
+    # In this case, both the current session and any active session are revoked.
+    #
+    # @param token [TokenAuthority::RefreshToken] the refresh token to validate
+    # @param client_id [String] the client ID attempting the refresh
+    # @param resources [Array<String>] resource indicators for the new tokens
+    # @param scopes [Array<String>] scopes for the new tokens
+    #
+    # @return [TokenAuthority::Session] the newly created session
+    #
+    # @raise [TokenAuthority::ServerError] if the token JTI doesn't match
+    # @raise [TokenAuthority::InvalidGrantError] if the token is invalid
+    # @raise [TokenAuthority::RevokedSessionError] if replay attack is detected
+    def refresh(token:, client_id:, resources: [], scopes: [])
+      instrument("session.refresh") do
+        raise TokenAuthority::ServerError, I18n.t("token_authority.errors.mismatched_refresh_token") unless token.jti == refresh_token_jti
+        raise TokenAuthority::InvalidGrantError unless token.valid?
+
+        # Detect stolen refresh token and replay attacks, and then revoke current active token authority session
+        unless created_status? && client_id == token_authority_authorization_grant.resolved_client.public_id
+          session = token_authority_authorization_grant.active_token_authority_session || self
+          session.update(status: "revoked")
+          raise TokenAuthority::RevokedSessionError.new(
+            client_id:,
+            refreshed_session_id: id,
+            revoked_session_id: session.id,
+            user_id:
+          )
+        end
+
+        create_token_authority_session(grant: token_authority_authorization_grant, resources:, scopes:) do
+          update(status: "refreshed")
+        end
+      end
+    rescue TokenAuthority::ServerError => error
+      raise TokenAuthority::ServerError, error.message
+    end
+
+    # Revokes this session and any active session for the same authorization grant.
+    #
+    # This ensures that revoking any token (access or refresh) invalidates the
+    # entire token family, preventing continued use after revocation. Emits a
+    # security event for audit logging.
+    #
+    # @param reason [String] the reason for revocation (default: "revocation_requested")
+    # @param request_id [String, nil] the request ID for correlation in logs
+    #
+    # @return [void]
+    #
+    # @example
+    #   session.revoke_self_and_active_session(
+    #     reason: "user_logout",
+    #     request_id: request.uuid
+    #   )
+    def revoke_self_and_active_session(reason: "revocation_requested", request_id: nil)
+      instrument("session.revoke") do
+        related_session_ids = []
+        ActiveRecord::Base.transaction do
+          update(status: "revoked")
+          active_session = token_authority_authorization_grant.active_token_authority_session
+          if active_session && active_session.id != id
+            active_session.update(status: "revoked")
+            related_session_ids << active_session.id
+          end
+        end
+
+        notify_event("security.session.revoked",
+          request_id: request_id,
+          session_id: id,
+          client_id: token_authority_authorization_grant.resolved_client&.public_id,
+          reason: reason,
+          related_session_ids: related_session_ids)
+      end
+    end
+
+    # Revokes the session associated with a token JTI.
+    #
+    # Searches for a session by either access token or refresh token JTI.
+    # This is the generic revocation method used when the token type is unknown.
+    #
+    # @param jti [String] the JWT identifier from the token
+    #
+    # @return [void]
+    #
+    # @note Returns silently if no session is found
+    def self.revoke_for_token(jti:)
+      # Must use find_by in this manner due to AR encryption
+      token_authority_session = find_by(access_token_jti: jti) || find_by(refresh_token_jti: jti)
+      execute_revocation(token_authority_session:)
+    end
+
+    # Revokes the session associated with an access token JTI.
+    #
+    # More efficient than revoke_for_token when the token type is known.
+    #
+    # @param access_token_jti [String] the access token's JWT identifier
+    #
+    # @return [void]
+    def self.revoke_for_access_token(access_token_jti:)
+      token_authority_session = find_by(access_token_jti:)
+      execute_revocation(token_authority_session:)
+    end
+
+    # Revokes the session associated with a refresh token JTI.
+    #
+    # More efficient than revoke_for_token when the token type is known.
+    #
+    # @param refresh_token_jti [String] the refresh token's JWT identifier
+    #
+    # @return [void]
+    def self.revoke_for_refresh_token(refresh_token_jti:)
+      token_authority_session = find_by(refresh_token_jti:)
+      execute_revocation(token_authority_session:)
+    end
+
+    class << self
+      # Internal helper to execute the revocation of a session.
+      #
+      # @param token_authority_session [TokenAuthority::Session, nil] the session to revoke
+      #
+      # @return [void]
+      #
+      # @api private
+      def execute_revocation(token_authority_session:)
+        return if token_authority_session.blank?
+
+        token_authority_session.revoke_self_and_active_session
+      end
+    end
+  end
+end

data/app/models/token_authority/software_statement.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Value object for parsing and validating software statements (signed JWT metadata)
+  class SoftwareStatement
+    STANDARD_CLAIMS = %i[
+      redirect_uris
+      token_endpoint_auth_method
+      grant_types
+      response_types
+      client_name
+      client_uri
+      logo_uri
+      scope
+      contacts
+      tos_uri
+      policy_uri
+      jwks_uri
+      jwks
+      software_id
+      software_version
+    ].freeze
+
+    attr_reader :raw_jwt, :payload, :header
+
+    def initialize(raw_jwt:, payload:, header:, verified: false)
+      @raw_jwt = raw_jwt
+      @payload = payload.with_indifferent_access
+      @header = header.with_indifferent_access
+      @verified = verified
+    end
+
+    class << self
+      def decode(jwt)
+        payload, header = JWT.decode(jwt, nil, false)
+        new(raw_jwt: jwt, payload: payload, header: header, verified: false)
+      rescue JWT::DecodeError => e
+        raise TokenAuthority::InvalidSoftwareStatementError, e.message
+      end
+
+      def decode_and_verify(jwt, jwks:)
+        jwk_set = jwks.is_a?(JWT::JWK::Set) ? jwks : JWT::JWK::Set.new(jwks)
+        algorithms = jwk_set.map { |key| key[:alg] }.compact.uniq
+        algorithms = ["RS256"] if algorithms.empty?
+
+        payload, header = JWT.decode(jwt, nil, true, {algorithms: algorithms, jwks: jwk_set})
+        new(raw_jwt: jwt, payload: payload, header: header, verified: true)
+      rescue JWT::DecodeError => e
+        raise TokenAuthority::InvalidSoftwareStatementError, e.message
+      end
+    end
+
+    STANDARD_CLAIMS.each do |claim|
+      define_method(claim) { payload[claim] }
+    end
+
+    def claims
+      payload.slice(*STANDARD_CLAIMS)
+    end
+
+    def trusted?
+      @verified
+    end
+
+    def to_h
+      claims
+    end
+  end
+end

data/app/views/token_authority/authorization_grants/new.html.erb

@@ -0,0 +1,25 @@
+<div>
+  <h2><%= t('token_authority.authorization_grants.new.title') %></h2>
+  <p><%= t('token_authority.authorization_grants.new.lede') %></p>
+  <p><strong><%= client_name %></strong></p>
+  <% if resources.any? %>
+    <p><%= t('token_authority.authorization_grants.new.resources_heading') %></p>
+    <ul>
+      <% resources.each do |resource| %>
+        <li><%= resource_display_name(resource) %></li>
+      <% end %>
+    </ul>
+  <% end %>
+  <% if scopes.any? %>
+    <p><%= t('token_authority.authorization_grants.new.scopes_heading') %></p>
+    <ul>
+      <% scopes.each do |scope| %>
+        <li><%= scope_display_name(scope) %></li>
+      <% end %>
+    </ul>
+  <% end %>
+  <div>
+    <%= button_to t('token_authority.authorization_grants.new.reject_cta'), authorization_grants_path, params: { approve: false } %>
+    <%= button_to t('token_authority.authorization_grants.new.approve_cta'), authorization_grants_path, params: { approve: true } %>
+  </div>
+</div>

data/app/views/token_authority/client_error.html.erb

@@ -0,0 +1,8 @@
+<div>
+  <h2><%= t('token_authority.client_error.title') %></h2>
+  <p><%= t('token_authority.client_error.lede') %></p>
+  <div>
+    <h3><%= error_class %></h3>
+    <p><%= error_message %></p>
+  </div>
+</div>