masks-server 0.7.0

data/app/models/masks/server/client_assertion.rb

@@ -0,0 +1,59 @@
+module Masks
+  module Server
+    class ClientAssertion
+      class Refused < StandardError; end
+
+      TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".freeze
+      SUBJECT = "that client assertion".freeze
+
+      attr_reader :token
+
+      def self.issuer_of(token)
+        claims = JWT.decode(token.to_s, nil, false).first
+
+        claims["sub"].presence || claims["iss"].presence
+      rescue JWT::DecodeError
+        nil
+      end
+
+      def initialize(token, client:, audiences:)
+        @token = token.to_s
+        @client = client
+        @audiences = Array(audiences).map { |one| one.to_s.chomp("/") }
+      end
+
+      def verify!
+        keys = ClientKeys.new(client)
+        claims, = keys.decode(token, subject: SUBJECT)
+
+        named!(claims)
+        addressed!(claims)
+        keys.timely!(claims, subject: SUBJECT)
+
+        raise Refused, "a client assertion must carry a jti" if claims["jti"].blank?
+
+        keys.once!(claims, kind: "client-assertion", subject: SUBJECT)
+
+        self
+      rescue ClientKeys::Refused => e
+        raise Refused, e.message
+      end
+
+      private
+
+        attr_reader :client, :audiences
+
+        def named!(claims)
+          unless claims["iss"] == client.client_id && claims["sub"] == client.client_id
+            raise Refused, "a client assertion must name the client as both iss and sub"
+          end
+        end
+
+        def addressed!(claims)
+          named = Array(claims["aud"]).map { |one| one.to_s.chomp("/") }
+
+          raise Refused, "that client assertion was made for another audience" if (named & audiences).empty?
+        end
+    end
+  end
+end

data/app/models/masks/server/client_keys.rb

@@ -0,0 +1,130 @@
+module Masks
+  module Server
+    class ClientKeys
+      class Refused < StandardError; end
+
+      LIFETIME = 5.minutes
+      OPEN_TIMEOUT = 2
+      READ_TIMEOUT = 3
+      SECRET = %w[d p q dp dq qi k].freeze
+      ALGORITHMS = %w[RS256 RS384 RS512 PS256 PS384 PS512 ES256 ES384 ES512].freeze
+      KINDS = %w[RSA EC].freeze
+      LEEWAY = 30
+      LONGEST = 1.hour
+
+      class << self
+        def check!(value)
+          held = value.is_a?(String) ? JSON.parse(value) : value
+          keys = held.is_a?(Hash) ? held["keys"] : nil
+
+          raise Refused, "must be a JSON Web Key Set with a keys array" unless keys.is_a?(Array) && keys.any?
+
+          keys.each do |key|
+            raise Refused, "every key must be a JSON object" unless key.is_a?(Hash)
+            raise Refused, "#{key['kty'].presence || 'that'} is not a kind of key a client signs with" unless KINDS.include?(key["kty"])
+            raise Refused, "a client's keys must be public" if key.keys.any? { |field| SECRET.include?(field.to_s) }
+
+            JWT::JWK.new(key).verify_key
+          end
+
+          held
+        rescue JSON::ParserError
+          raise Refused, "is not JSON"
+        rescue JWT::JWKError, OpenSSL::PKey::PKeyError, ArgumentError => e
+          raise Refused, "holds a key that cannot be read: #{e.message}"
+        end
+
+        def fetch(uri)
+          held = URI.parse(uri.to_s)
+
+          raise Refused, "must be an https URL" unless held.is_a?(URI::HTTPS) || (::Rails.env.local? && held.is_a?(URI::HTTP))
+
+          check!(Outbound.fetch!(held, open: OPEN_TIMEOUT, read: READ_TIMEOUT))
+        rescue URI::InvalidURIError
+          raise Refused, "is not a URI"
+        rescue Outbound::Refused => e
+          raise Refused, e.message
+        end
+      end
+
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def keys(fresh: false)
+        return Array(client.jwks&.dig("keys")) if client.jwks.present?
+        return [] if client.jwks_uri.blank?
+
+        ::Rails.cache.delete(cache_key) if fresh
+
+        Array(::Rails.cache.fetch(cache_key, expires_in: LIFETIME) { self.class.fetch(client.jwks_uri) }["keys"])
+      end
+
+      def remote?
+        client.jwks.blank? && client.jwks_uri.present?
+      end
+
+      def decode(token, subject: "that token")
+        header = JWT.decode(token.to_s, nil, false).last
+        algorithm = header["alg"].to_s
+
+        raise Refused, "#{algorithm.presence || 'that'} is not an algorithm #{subject} may be signed with" unless ALGORITHMS.include?(algorithm)
+
+        verified = attempt(token, header, algorithm, fresh: false)
+        verified ||= attempt(token, header, algorithm, fresh: true) if remote? && unknown_kid?(header)
+
+        verified || raise(Refused, "#{subject} was not signed by a key this client registered")
+      rescue JWT::DecodeError
+        raise Refused, "#{subject} is not a readable JWT"
+      end
+
+      def timely!(claims, subject:)
+        now = Time.current.to_i
+        expires = claims["exp"]
+
+        raise Refused, "#{subject} must say when it expires" unless expires.is_a?(Numeric)
+        raise Refused, "#{subject} has expired" if expires < now - LEEWAY
+        raise Refused, "#{subject} lives longer than #{LONGEST.inspect}" if expires > now + LONGEST.to_i + LEEWAY
+        raise Refused, "#{subject} was made in the future" if claims["iat"].is_a?(Numeric) && claims["iat"] > now + LEEWAY
+        raise Refused, "#{subject} is not valid yet" if claims["nbf"].is_a?(Numeric) && claims["nbf"] > now + LEEWAY
+      end
+
+      def once!(claims, kind:, subject:)
+        remaining = [ claims["exp"].to_i - Time.current.to_i + LEEWAY, LEEWAY ].max
+
+        raise Refused, "#{subject} has already been used" unless Replay.first?(kind, claims["jti"], within: client.id, expires_in: remaining)
+      end
+
+      private
+
+        def unknown_kid?(header)
+          kid = header["kid"].presence
+
+          kid.nil? || keys.none? { |jwk| jwk.is_a?(Hash) && jwk["kid"] == kid }
+        end
+
+        def attempt(token, header, algorithm, fresh:)
+          candidates(header, fresh).each do |jwk|
+            return [ *JWT.decode(token.to_s, JWT::JWK.new(jwk).verify_key, true, algorithms: [ algorithm ], verify_expiration: false) ]
+          rescue JWT::VerificationError, JWT::IncorrectAlgorithm, JWT::JWKError, OpenSSL::PKey::PKeyError, ArgumentError
+            next
+          end
+
+          nil
+        end
+
+        def candidates(header, fresh)
+          held = keys(fresh: fresh).select { |jwk| jwk.is_a?(Hash) && jwk["use"].to_s != "enc" }
+          kid = header["kid"].presence
+
+          kid ? held.select { |jwk| jwk["kid"] == kid } : held
+        end
+
+        def cache_key
+          "client-jwks:#{client.tenant_id}:#{client.id}:#{Digest::SHA256.hexdigest(client.jwks_uri.to_s)}"
+        end
+    end
+  end
+end

data/app/models/masks/server/client_logo.rb

@@ -0,0 +1,55 @@
+module Masks
+  module Server
+    class ClientLogo < ApplicationRecord
+      include TenantScoped
+
+      STORED = 256
+      OPEN_TIMEOUT = 3
+      READ_TIMEOUT = 5
+      WITHIN = 15
+
+      belongs_to :client
+
+      validates :client_id, uniqueness: { scope: :tenant_id }
+
+      class << self
+        def fetch!(client)
+          return forget(client) if client.logo_uri.blank?
+
+          bytes = Outbound.fetch!(URI.parse(client.logo_uri), open: OPEN_TIMEOUT, read: READ_TIMEOUT, within: WITHIN)
+
+          raise Pictures::Unreadable, "a logo has to be an image" if Pictures.sniff(bytes).nil?
+
+          keep(client, Pictures.square(bytes, STORED))
+        end
+
+        def forget(client)
+          transaction do
+            where(client_id: client.id).delete_all
+            client.update_column(:logo_digest, nil)
+          end
+        end
+
+        private
+
+          def keep(client, square)
+            digest = Pictures.digest(square)
+
+            transaction do
+              find_or_initialize_by(client_id: client.id).update!(
+                source_uri: client.logo_uri, content_type: Pictures::CONTENT_TYPE,
+                digest: digest, byte_size: square.bytesize, data: square
+              )
+              client.update_column(:logo_digest, digest)
+            end
+          rescue ActiveRecord::RecordNotUnique
+            retry
+          end
+      end
+
+      def resized(size)
+        Pictures.resized(data, digest, size, stored: STORED, kind: "client-logo")
+      end
+    end
+  end
+end

data/app/models/masks/server/client_metadata_document.rb

@@ -0,0 +1,178 @@
+module Masks
+  module Server
+    class ClientMetadataDocument
+      class Refused < StandardError; end
+
+      CEILING = 5.kilobytes
+      OPEN_TIMEOUT = 2
+      READ_TIMEOUT = 3
+      WITHIN = 5
+      SHORTEST = 5.minutes
+      LIFETIME = 1.hour
+      LONGEST = 24.hours
+      REFUSAL_LIFETIME = 5.minutes
+      NAME_LIMIT = 100
+      WINDOW = 10.minutes
+      TENANT_FACTOR = 10
+      AUTH_METHODS = %w[none private_key_jwt].freeze
+      DEFAULT_AUTH_METHOD = "none".freeze
+      FORBIDDEN = %w[client_secret client_secret_expires_at registration_access_token registration_client_uri].freeze
+      STRINGS = %w[client_name client_uri logo_uri tos_uri policy_uri jwks_uri backchannel_logout_uri
+                   token_endpoint_auth_method application_type subject_type sector_identifier_uri scope].freeze
+      LISTS = %w[redirect_uris post_logout_redirect_uris grant_types response_types resources authorization_details_types].freeze
+      FLAGS = %w[backchannel_logout_session_required dpop_bound_access_tokens require_pushed_authorization_requests
+                 require_signed_request_object].freeze
+
+      class << self
+        def url?(client_id)
+          problem_with(client_id).nil?
+        end
+
+        def problem_with(client_id)
+          value = client_id.to_s
+          uri = URI.parse(value)
+
+          if !uri.is_a?(URI::HTTPS) && !(::Rails.env.local? && uri.is_a?(URI::HTTP))
+            "must be an https URL"
+          elsif value.length > Client::URI_LIMIT
+            "must be at most #{Client::URI_LIMIT} characters"
+          elsif uri.host.blank? || uri.userinfo.present? || uri.fragment
+            "must name a host, and carry no credentials or fragment"
+          elsif uri.path.blank? || uri.path == "/"
+            "must have a path"
+          elsif uri.path.split("/").intersect?(%w[. ..])
+            "must not contain dot segments"
+          end
+        rescue URI::InvalidURIError
+          "is not a URL"
+        end
+
+        def resolve(client_id)
+          held = Client.find_by(client_id: client_id)
+
+          return nil if held&.archived? || held&.protocol == SamlIdentity::PROTOCOL
+          return held if held && !held.metadata_stale?
+          return nil unless Current.tenant&.registers?
+          return nil if held.nil? && crowded?
+
+          new(client_id).save!(held)
+        rescue Refused => e
+          ::Rails.logger.info("masks: client metadata document #{client_id} refused: #{e.message}")
+          nil
+        end
+
+        def crowded?
+          limit = ::Rails.configuration.masks.registration_limit
+          key = "masks:client-metadata-documents:#{Current.tenant&.id}:#{Time.current.to_i / WINDOW.to_i}"
+          here = ::Rails.cache.increment("#{key}:#{Current.ip_address}", 1, expires_in: WINDOW)
+          anywhere = ::Rails.cache.increment(key, 1, expires_in: WINDOW)
+
+          (here.to_i > limit || anywhere.to_i > limit * TENANT_FACTOR).tap do |crowded|
+            ::Rails.logger.info("masks: too many new client metadata documents") if crowded
+          end
+        end
+
+        def refusal_key(client_id)
+          "masks:client-metadata-document:#{Current.tenant&.id}:#{Digest::SHA256.hexdigest(client_id)}"
+        end
+      end
+
+      attr_reader :client_id
+
+      def initialize(client_id)
+        @client_id = client_id
+      end
+
+      def save!(held)
+        refused = ::Rails.cache.read(refusal_key)
+        raise Refused, refused if refused
+
+        document, expires_at = fetch
+        client = held || Client.new(client_id: client_id, dynamic: true)
+        created = client.new_record?
+
+        client.assign_attributes(attributes(document, expires_at, approved: client.approved?))
+        client.save!
+
+        Event.record!(created ? Event::CLIENT_REGISTERED : Event::CLIENT_UPDATED,
+                      client: client, name: client.name, dynamic: true, document: true)
+
+        client
+      rescue ActiveRecord::RecordNotUnique
+        Client.find_by!(client_id: client_id)
+      rescue ActiveRecord::RecordInvalid => e
+        refuse!(e.record.errors.full_messages.join("; "))
+      rescue Client::ScopesUnavailable, Outbound::Refused => e
+        refuse!(e.message)
+      end
+
+      private
+
+        def refusal_key
+          self.class.refusal_key(client_id)
+        end
+
+        def refuse!(message)
+          ::Rails.cache.write(refusal_key, message, expires_in: REFUSAL_LIFETIME)
+          raise Refused, message
+        end
+
+        def fetch
+          response = Outbound.get!(
+            URI.parse(client_id),
+            open: OPEN_TIMEOUT, read: READ_TIMEOUT, ceiling: CEILING, within: WITHIN,
+            headers: { "Accept" => "application/json" }
+          )
+
+          [ checked(JSON.parse(response.body)), Time.current + lifetime(response["Cache-Control"]) ]
+        rescue JSON::ParserError
+          refuse!("is not JSON")
+        end
+
+        def checked(document)
+          refuse!("is not a JSON object") unless document.is_a?(Hash)
+          refuse!("names #{document['client_id'].to_s.truncate(80).inspect} as its client_id") unless document["client_id"] == client_id
+
+          forbidden = FORBIDDEN & document.keys
+          refuse!("must not carry #{forbidden.join(', ')}") if forbidden.any?
+
+          STRINGS.each { |field| typed!(document, field, "a string", String) }
+          FLAGS.each { |field| typed!(document, field, "true or false", TrueClass, FalseClass) }
+          LISTS.each do |field|
+            next if document[field].nil?
+
+            refuse!("#{field} must be an array of strings") unless document[field].is_a?(Array) && document[field].all?(String)
+          end
+          typed!(document, "jwks", "an object", Hash)
+
+          method = document["token_endpoint_auth_method"] || DEFAULT_AUTH_METHOD
+          refuse!("token_endpoint_auth_method must be one of #{AUTH_METHODS.join(', ')}") unless AUTH_METHODS.include?(method)
+
+          document
+        end
+
+        def typed!(document, field, expected, *types)
+          value = document[field]
+          return if value.nil? || types.any? { |type| value.is_a?(type) }
+
+          refuse!("#{field} must be #{expected}")
+        end
+
+        def lifetime(cache_control)
+          directives = cache_control.to_s.downcase.split(",").map(&:strip)
+
+          return SHORTEST if directives.intersect?(%w[no-store no-cache])
+
+          age = directives.filter_map { |directive| directive[/\Amax-age=(\d+)\z/, 1] }.first
+          age ? Integer(age).seconds.clamp(SHORTEST, LONGEST) : LIFETIME
+        end
+
+        def attributes(document, expires_at, approved:)
+          held = Client.registered_attributes(document, name: URI.parse(client_id).host, auth_method: DEFAULT_AUTH_METHOD)
+          held = held.slice(:name, :client_uri, :logo_uri, :tos_uri, :policy_uri) if approved
+
+          held.merge(name: held[:name].truncate(NAME_LIMIT), metadata_expires_at: expires_at)
+        end
+    end
+  end
+end

data/app/models/masks/server/code_factors.rb

@@ -0,0 +1,103 @@
+module Masks
+  module Server
+    module CodeFactors
+      SPECS = {
+        "email" => {
+          channel: ConfirmationCode::EMAIL, sent_on: "email_factor", on: :email_factor_at,
+          verified: :email_verified_at, held: :email_factor?, amr: "otp", icon: :email,
+          enabled: Event::EMAIL_CODES_ENABLED, disabled: Event::EMAIL_CODES_DISABLED,
+          deliverable: -> { ActorMailer.deliverable? },
+          mask: ->(address) { name, domain = address.split("@", 2); "#{name.to_s[0]}•••@#{domain}" }
+        },
+        "sms" => {
+          channel: ConfirmationCode::PHONE, sent_on: "phone_factor", on: :phone_factor_at,
+          verified: :phone_verified_at, held: :phone_factor?, amr: "sms", icon: :device,
+          enabled: Event::TEXT_CODES_ENABLED, disabled: Event::TEXT_CODES_DISABLED,
+          deliverable: -> { Texting.deliverable? },
+          mask: ->(address) { "•••• #{address.last(4)}" }
+        }
+      }.freeze
+
+      FACTORS = SPECS.keys.freeze
+
+      INDEPENDENT_OF_THE_INBOX = %w[pwd swk].freeze
+
+      class << self
+        def known?(factor)
+          SPECS.key?(factor.to_s)
+        end
+
+        def spec(factor)
+          SPECS.fetch(factor.to_s)
+        end
+
+        def held?(actor, factor)
+          known?(factor) && actor.public_send(spec(factor)[:held])
+        end
+
+        def offered?(actor, factor, policy: SignInPolicy.for(tenant: Current.tenant))
+          known?(factor) && (actor.manages? || policy.second_factor?(factor))
+        end
+
+        def confirmed?(actor, factor)
+          address(actor, factor).present? && actor.public_send(spec(factor)[:verified]).present?
+        end
+
+        def deliverable?(factor)
+          spec(factor)[:deliverable].call
+        end
+
+        def address(actor, factor)
+          actor.public_send(spec(factor)[:channel])
+        end
+
+        def masked(actor, factor)
+          spec(factor)[:mask].call(address(actor, factor).to_s)
+        end
+
+        def amr(factor)
+          spec(factor)[:amr]
+        end
+
+        def icon(factor)
+          spec(factor)[:icon]
+        end
+
+        def send!(actor, factor, journey:)
+          held = spec(factor)
+          to = address(actor, factor)
+          token, code = ConfirmationCode.open!(actor: actor, channel: held[:sent_on], address: to)
+
+          Confirmations.deliver(held[:channel], to, code, journey: journey)
+
+          token
+        end
+
+        def sent(actor, factor, id)
+          return nil if id.blank? || !known?(factor)
+
+          token = ConfirmationCode.find_by(id: id, actor_id: actor.id)
+
+          token if token&.live? && token.channel == spec(factor)[:sent_on] && token.address == address(actor, factor)
+        end
+
+        def enable!(actor, factor)
+          held = spec(factor)
+          now = Time.current
+
+          actor.update!(held[:on] => now, held[:verified] => actor.public_send(held[:verified]) || now)
+
+          Event.record!(held[:enabled], actor: actor)
+        end
+
+        def disable!(actor, factor, by: :subject)
+          return false unless held?(actor, factor)
+
+          actor.update!(spec(factor)[:on] => nil)
+
+          Event.record!(spec(factor)[:disabled], actor: actor, by: by)
+        end
+      end
+    end
+  end
+end

data/app/models/masks/server/confirmation_code.rb

@@ -0,0 +1,110 @@
+module Masks
+  module Server
+    class ConfirmationCode < Token
+      DIGITS = 6
+      ATTEMPTS = 5
+      RESEND_AFTER = 30.seconds
+
+      EMAIL = "email".freeze
+      PHONE = "phone".freeze
+      INBOX = "inbox".freeze
+
+      WINDOW = 15.minutes
+      INBOX_PER_IP = 4
+
+      class << self
+        def lifetime
+          10.minutes
+        end
+
+        def open!(actor:, channel:, address:)
+          where(actor_id: actor.id).live.where("payload->>'channel' = ?", channel).update_all(consumed_at: Time.current)
+
+          mint_code!(actor: actor, channel: channel, address: address)
+        end
+
+        def open_inbox!(address:, ip: nil)
+          inbox.where("payload->>'address' = ?", address).live.update_all(consumed_at: Time.current)
+
+          mint_code!(actor: nil, channel: INBOX, address: address, ip: ip)
+        end
+
+        def inbox_crowded?(address:, ip: nil)
+          recent = inbox.where(created_at: WINDOW.ago..)
+          limit = ::Rails.configuration.masks.recovery_limit
+
+          recent.where("payload->>'address' = ?", address).count >= limit ||
+            (ip.present? && recent.where("payload->>'ip' = ?", ip).count >= limit * INBOX_PER_IP)
+        end
+
+        def crowded?(actor:, channel:)
+          where(actor_id: actor.id, created_at: WINDOW.ago..)
+            .where("payload->>'channel' = ?", channel)
+            .count >= ::Rails.configuration.masks.recovery_limit
+        end
+
+        def inbox
+          where(actor_id: nil).where("payload->>'channel' = ?", INBOX)
+        end
+
+        def digest(salt, code)
+          OpenSSL::HMAC.hexdigest("SHA256", salt.to_s, code.to_s)
+        end
+
+        def generate
+          code = SecureRandom.random_number(10**DIGITS).to_s.rjust(DIGITS, "0")
+          salt = SecureRandom.hex(16)
+
+          [ code, { "salt" => salt, "digest" => digest(salt, code) } ]
+        end
+
+        def matches?(held, code)
+          entered = code.to_s.delete("^0-9")
+
+          entered.length == DIGITS &&
+            ActiveSupport::SecurityUtils.secure_compare(digest(held["salt"], entered), held["digest"].to_s)
+        end
+
+        private
+
+          def mint_code!(actor:, channel:, address:, ip: nil)
+            code, secret = generate
+
+            token = mint!(
+              actor: actor,
+              payload: { "channel" => channel, "address" => address, **secret, "attempts" => 0, "ip" => ip }.compact
+            )
+
+            [ token, code ]
+          end
+      end
+
+      def channel
+        held("channel")
+      end
+
+      def address
+        held("address")
+      end
+
+      def resendable?
+        created_at <= RESEND_AFTER.ago
+      end
+
+      def verify(code)
+        matched = self.class.matches?(payload, code)
+
+        with_lock do
+          next false unless live?
+
+          attempts = held("attempts").to_i + 1
+          spent = matched || attempts >= ATTEMPTS
+
+          update!(payload: payload.merge("attempts" => attempts), consumed_at: spent ? Time.current : nil)
+
+          matched
+        end
+      end
+    end
+  end
+end

data/app/models/masks/server/confirmations.rb

@@ -0,0 +1,51 @@
+module Masks
+  module Server
+    module Confirmations
+      class << self
+        def send_code(actor, channel, journey:)
+          token, code = ConfirmationCode.open!(actor: actor, channel: channel, address: actor.public_send(channel))
+
+          deliver(channel, actor.public_send(channel), code, journey: journey)
+
+          if channel == ConfirmationCode::EMAIL
+            Event.record!(Event::EMAIL_VERIFICATION_SENT, actor: actor, email: actor.email, by_code: true)
+          else
+            Event.record!(Event::PHONE_VERIFICATION_SENT, actor: actor)
+          end
+
+          token
+        end
+
+        def deliver(channel, to, code, journey:)
+          if channel == ConfirmationCode::EMAIL
+            ActorMailer.confirmation_code(to, code, journey: journey).deliver_later
+          else
+            Texting.deliver_later(to: to, body: I18n.t("texts.code", code: code, tenant: journey.heading))
+          end
+        end
+
+        def request_approval(actor, journey:)
+          Event.record!(Event::APPROVAL_REQUESTED, actor: actor)
+
+          return unless ActorMailer.deliverable?
+
+          approvers = Actor.holding(Scopes::MANAGE).or(Actor.holding(Scopes::MANAGE_SUPPORT))
+
+          approvers.where.not(email_verified_at: nil).find_each do |manager|
+            ActorMailer.approval_requested(manager, actor, journey: journey).deliver_later
+          end
+        end
+
+        def approve!(actor, journey:)
+          actor.update!(pending_approval_at: nil)
+
+          Event.record!(Event::ACTOR_APPROVED, actor: actor, by: journey.by)
+
+          return if actor.email.blank?
+
+          ActorMailer.approved(actor, journey: journey).deliver_later
+        end
+      end
+    end
+  end
+end