usernames 0.1.3

data/lib/usernames/reserved.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Usernames
+  # Reserved names: the exact list (config.reserved, your routes,
+  # the bundled system, mailbox and web words) and the impersonation list
+  # (config.forbidden, the bundled impersonation words, your app's name),
+  # with config.allowed lifting individual words.
+  #
+  # The two lists are matched differently because they fail differently.
+  # Somebody posing as staff types `adm1n`, `ad.min`, `admin_bob` or
+  # `admins`, so impersonation words are looked for in every form the name
+  # can be read as. The thousand-odd exact words are paths and mailboxes
+  # that only collide when spelled exactly: folding trailing digits over
+  # them is what refused `game969` in production, and matching them as
+  # prefixes is what refused `badminton_fan`.
+  module Reserved
+    SEPARATORS = "_.-"
+
+    # A segment is what sits between separators and digit runs:
+    # `adm1n_bob` reads as adm, n, bob.
+    SEGMENT_BOUNDARY = /[_.-]+|\d+/
+
+    # Names that read as a well-known URI or as an IDNA/punycode label
+    # whatever follows: `/.well-known/…` is served by the web server, and
+    # `xn--…` is how a Unicode lookalike travels as ASCII.
+    PREFIXES = %w[.well-known xn--].freeze
+
+    # The compiled sets for one Usernames::Rules. Every word is an ASCII
+    # comparison key, so a lookup is one Set#include?. :nodoc:
+    Sets = ::Data.define(:exact, :custom, :impersonation, :allowed)
+
+    class << self
+      # The kind of reservation that matched — :impersonation, :exact, :route
+      # or :custom — or nil when the name is free to use. `key` is
+      # Usernames.comparison_key of a name that already passed every format
+      # rule; `rules` is the Usernames::Rules in force.
+      #
+      # config.allowed lifts any of them, but only for exactly that name:
+      # allowing `help` frees `help`, not `help_desk`.
+      #
+      # A word in config.forbidden is matched as an impersonation
+      # word and reported as :impersonation; :custom names a config.reserved
+      # word that is not bundled. A reserved prefix (`.well-known`, `xn--`)
+      # is reported as :exact.
+      def verdict(key, rules)
+        sets = sets_for(rules)
+        return if sets.allowed.include?(key)
+
+        if impersonation?(key, sets.impersonation) then :impersonation
+        elsif sets.custom.include?(key) then :custom
+        elsif sets.exact.include?(key) || prefix?(key) then :exact
+        elsif rules.reserve_routes && routes.include?(key) then :route
+        end
+      end
+
+      # Whether any spelling of the name is an impersonation entry: the name
+      # exactly as typed (so a custom entry that is itself digits or
+      # separators, `web3`, still forbids itself), and — as typed and
+      # leet-folded — whole and without trailing digits (separators removed),
+      # and every segment. The first spelling that is an entry answers, so
+      # most names are refused or passed in a few lookups.
+      def impersonation?(key, entries)
+        return true if entries.include?(key)
+
+        [key, leet(key)].uniq.any? do |form|
+          entries.include?(form.delete(SEPARATORS)) ||
+            entries.include?(form.sub(/\d+\z/, "").delete(SEPARATORS)) ||
+            form.split(SEGMENT_BOUNDARY).any? { |segment| entries.include?(segment) }
+        end
+      end
+
+      def prefix?(key)
+        key.start_with?(*PREFIXES)
+      end
+
+      # The digit folds of data/offensive/leet.yml: 0→o 1→i 3→e 4→a 5→s 7→t.
+      def leet(string)
+        from, to = digit_folds
+        string.tr(from, to)
+      end
+
+      # Where a bundled reserved word comes from, for `usernames:reserved`:
+      # a Usernames::Data::Provenance (category, source, licence, reason),
+      # or nil for a word the gem does not ship.
+      def source_of(word)
+        Data.reserved_provenance[word.to_s.downcase(:ascii)]
+      end
+
+      # The first path segment of every static route the app draws, collected
+      # once and kept until reset_routes! (the engine calls it when routes
+      # reload). Empty outside a Rails application.
+      def routes
+        @routes ||= rails_routes
+      end
+
+      def reset_routes!
+        @routes = nil
+      end
+
+      # The app's own name as it would be typed: `config.app_name`
+      # when it is a String, else the module of the Rails application —
+      # `RecipeBox::Application` reserves `recipe_box` and
+      # `recipebox`. None when opted out (`false`) or when there is no
+      # named application.
+      def app_names(rules)
+        name = rules.app_name
+        name = detected_app_name if name.nil?
+        return [] unless name.is_a?(String)
+
+        underscored = name.underscore.downcase(:ascii).gsub(/[^a-z0-9]+/, "_").gsub(/\A_+|_+\z/, "")
+        [underscored, underscored.delete("_")].reject(&:empty?).uniq
+      end
+
+      private
+
+      def sets_for(rules)
+        rules.compiled(:reserved) do
+          bundled = Data.reserved.to_set
+          reserved = keys(rules.reserved)
+          Sets.new(
+            exact: (reserved & bundled).freeze,
+            custom: (reserved - bundled).freeze,
+            impersonation: impersonation_entries(keys(rules.forbidden) | app_names(rules)).freeze,
+            allowed: keys(rules.allowed)
+          )
+        end
+      end
+
+      # Each word as the matcher stores it: itself, leet-folded, and the plural
+      # of both; and, for an entry written with separators (`my_app`), the
+      # same again without them — the name side is read without separators
+      # too, and an entry with one could otherwise only ever match literally.
+      def impersonation_entries(words)
+        words.each_with_object(Set.new) do |word, entries|
+          [word, word.delete(SEPARATORS)].uniq.each do |form|
+            [form, leet(form)].each { |spelling| entries << spelling << "#{spelling}s" }
+          end
+        end
+      end
+
+      def keys(words)
+        words.to_set { |word| word.strip.downcase(:ascii) }.freeze
+      end
+
+      def digit_folds
+        @digit_folds ||= begin
+          digits = Data.leet.fetch("digits")
+          [digits.keys.join, digits.values.join].map(&:freeze).freeze
+        end
+      end
+
+      def rails_routes
+        return Set.new.freeze unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        Routes.collect(::Rails.application.routes)
+      end
+
+      # Rails::Application subclasses are named `<App>::Application`; one
+      # defined at the top level (a script, a test) has no app name.
+      def detected_app_name
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        parent = ::Rails.application.class.module_parent
+        parent.name unless parent == Object
+      end
+    end
+
+    # The first path segment of an app's static routes, so a user
+    # called `login` cannot take /login from under the app's feet.
+    module Routes
+      # What a route's first segment may be: anything a username could be.
+      # Others (`@`, `~`) can never collide, so they are left out.
+      SEGMENT = /\A[a-z0-9._-]+\z/
+
+      class << self
+        # The frozen Set of first segments from an ActionDispatch::Routing::RouteSet.
+        #
+        # Reads each route's Journey AST: a path of the form `/literal`, then
+        # nothing, another `/`, or an optional group that starts with `/` or
+        # `.` (`/login(.:format)`, `/bar(/:x)`). A literal followed directly by a
+        # dot or a parameter (`/foo.:kind`, `/@:username`) is only part of a
+        # dynamic segment, and `/:username`, `/*path` have no literal at all.
+        # A mounted engine contributes its mount path, like any other route.
+        def collect(route_set)
+          route_set.routes.each_with_object(Set.new) do |route, segments|
+            segment = first_segment(route.path.spec)
+            segments << segment if segment
+          end.freeze
+        end
+
+        private
+
+        def first_segment(spec)
+          slash, literal, following = flatten(spec)
+          return unless slash&.type == :SLASH && literal&.type == :LITERAL && complete?(following)
+
+          segment = literal.left.to_s.downcase(:ascii)
+          segment if SEGMENT.match?(segment)
+        end
+
+        def complete?(node)
+          case node&.type
+          when nil, :SLASH then true
+          when :GROUP then %i[SLASH DOT].include?(flatten(node.left).first&.type)
+          else false
+          end
+        end
+
+        # A Journey path is a right-leaning tree of Cat nodes; this reads it
+        # as the list of nodes it spells, groups left whole.
+        def flatten(node)
+          node.type == :CAT ? flatten(node.left) + flatten(node.right) : [node]
+        end
+      end
+    end
+  end
+end

data/lib/usernames/result.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Usernames
+  # The answer to `Usernames.check`: whether a name may be registered, and if
+  # not, which rule said so.
+  #
+  #   reason     the error type a model would get (:username_reserved, :too_short…)
+  #   rule       for a content verdict, which kind of match it was: :impersonation,
+  #              :exact, :route, :custom, :severe, :strong, :hate_number, :adapter.
+  #              nil when the name is fine or failed a format rule (the reason
+  #              already names a format rule exactly).
+  #   canonical  the normalised name the rules were applied to
+  #   message    the error message in the current locale, or nil when ok.
+  #              Never contains what was typed — and never which word matched.
+  #
+  # `::Data`, not `Data`: inside this namespace `Data` is Usernames::Data.
+  Result = ::Data.define(:ok?, :reason, :rule, :canonical, :message) do
+    # `record` and `attribute` word the message the way that model's own
+    # error would be worded (see Failure#message).
+    def self.for(canonical, failure, record: nil, attribute: nil)
+      return new(ok?: true, reason: nil, rule: nil, canonical: canonical, message: nil) unless failure
+
+      new(ok?: false, reason: failure.reason, rule: failure.rule, canonical: canonical,
+          message: failure.message(record, attribute))
+    end
+  end
+
+  # One failed rule, as the pipeline hands it around before it becomes a
+  # Result (for the pure functions) or an Active Model error (for the
+  # validator). `details` are the interpolations the message needs, kept
+  # separate so the validator can hand them to errors.add and let a per-model
+  # translation win, exactly as for a Rails error. :nodoc:
+  Failure = ::Data.define(:reason, :rule, :details) do
+    def initialize(reason:, rule: nil, details: {})
+      super
+    end
+
+    # A Symbol :message in the details names the translation to use while the
+    # type stays `reason` — Active Model's own convention for errors.add.
+    #
+    # With a `record` (any instance of the model) and its `attribute`, the
+    # message is looked up exactly as that model's error would be
+    # (activerecord.errors.models.user.attributes.handle.too_short first, then
+    # up to errors.messages), so the browser hints and the availability
+    # check say what the form says.
+    def message(record = nil, attribute = nil)
+      return record.errors.generate_message(attribute, reason, details.dup) if record
+
+      I18n.t(details.fetch(:message, reason), scope: %i[errors messages], **details.except(:message)).to_s
+    end
+  end
+end

data/lib/usernames/rules/options.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Usernames
+  class Rules
+    # Every option the gem takes, checked once when a Rules is built — so an
+    # initializer typo (`config.case = :lower`, `length: 3`) fails at boot
+    # with the bad value named, instead of quietly meaning something else on
+    # the day somebody signs up.
+    module Options
+      NAMES = %i[
+        length separators edge_separators case first_character reserve_routes app_name
+        reserved forbidden allowed offensive on_adapter_failure generator unique_index
+      ].freeze
+
+      OFFENSIVE_NAMES = %i[severity languages allowed adapters].freeze
+      GENERATOR_NAMES = %i[adjectives nouns callable].freeze
+
+      SEPARATORS = %w[_ . -].freeze
+      CASES = %i[lowercase preserve].freeze
+      FIRST_CHARACTERS = %i[alphanumeric letter].freeze
+      SEVERITIES = %i[severe strong mild off].freeze
+      ADAPTER_FAILURE_MODES = %i[allow reject].freeze
+
+      OffensiveSettings = ::Data.define(*OFFENSIVE_NAMES)
+      GeneratorSettings = ::Data.define(*GENERATOR_NAMES)
+
+      attr_reader(*NAMES)
+
+      private
+
+      def assign(options)
+        unknown = options.keys - NAMES
+        raise ConfigurationError, "unknown option #{unknown.first.inspect} (known: #{NAMES.join(', ')})" if unknown.any?
+
+        assign_format(options)
+        assign_lists(options)
+        assign_offensive(options.fetch(:offensive))
+        assign_generator(options.fetch(:generator))
+        @reserve_routes = boolean(:reserve_routes, options.fetch(:reserve_routes))
+        @app_name = valid_app_name(options.fetch(:app_name))
+        @unique_index = valid_unique_index(options.fetch(:unique_index))
+      end
+
+      def assign_format(options)
+        @length = valid_length(options.fetch(:length))
+        @separators = valid_separators(options.fetch(:separators))
+        @edge_separators = boolean(:edge_separators, options.fetch(:edge_separators))
+        @case = one_of(:case, options.fetch(:case), CASES)
+        @first_character = one_of(:first_character, options.fetch(:first_character), FIRST_CHARACTERS)
+      end
+
+      def assign_lists(options)
+        @reserved = valid_words(:reserved, options.fetch(:reserved))
+        @forbidden = valid_words(:forbidden, options.fetch(:forbidden))
+        @allowed = valid_words(:allowed, options.fetch(:allowed))
+        @on_adapter_failure = one_of(:on_adapter_failure, options.fetch(:on_adapter_failure), ADAPTER_FAILURE_MODES)
+      end
+
+      def assign_offensive(offensive)
+        offensive = settings(:offensive, offensive, OFFENSIVE_NAMES)
+        @offensive = OffensiveSettings.new(
+          severity: one_of(:"offensive.severity", offensive[:severity], SEVERITIES),
+          languages: valid_languages(offensive[:languages]),
+          allowed: valid_words(:"offensive.allowed", offensive[:allowed]),
+          adapters: valid_adapters(offensive[:adapters])
+        )
+      end
+
+      def assign_generator(generator)
+        generator = settings(:generator, generator, GENERATOR_NAMES)
+        callable = generator[:callable]
+        unless callable.nil? || callable.respond_to?(:call)
+          invalid!(:generator, callable, "a callable such as ->(attempt) { … }")
+        end
+
+        @generator = GeneratorSettings.new(
+          adjectives: valid_words(:"generator.adjectives", generator[:adjectives]),
+          nouns: valid_words(:"generator.nouns", generator[:nouns]),
+          callable: callable
+        )
+      end
+
+      def valid_length(value)
+        valid = value.is_a?(Range) && value.begin.is_a?(Integer) && value.end.is_a?(Integer) &&
+                value.min.to_i >= 1
+        invalid!(:length, value, "a Range of whole numbers from 1 up, like 3..30") unless valid
+
+        value.min..value.max
+      end
+
+      def valid_separators(value)
+        unless value.is_a?(Array) && value.all? { |separator| SEPARATORS.include?(separator) }
+          invalid!(:separators, value, "a list drawn from #{SEPARATORS.map(&:inspect).join(', ')}, like %w[_]")
+        end
+
+        value.uniq.freeze
+      end
+
+      def one_of(name, value, choices)
+        invalid!(name, value, "one of #{choices.map(&:inspect).join(', ')}") unless choices.include?(value)
+
+        value
+      end
+
+      def boolean(name, value)
+        one_of(name, value, [true, false])
+      end
+
+      # A list of words, naming the one entry that is not a word rather than
+      # printing a list that may hold a thousand of them.
+      def valid_words(name, value)
+        invalid!(name, value, "a list of words, like %w[recipe]") unless value.is_a?(Array)
+        # An index, not the entry itself: the bad entry may be nil.
+        bad = value.index { |word| !word.is_a?(String) || word.strip.empty? }
+        raise ConfigurationError, "#{name} must be a list of words, like %w[recipe] (got #{value[bad].inspect} in it)" if bad
+
+        value.dup.freeze
+      end
+
+      # Only languages whose words ship: a language without data would refuse
+      # nothing, so a typo (`:sp`) or a language not tiered yet would switch
+      # the word check off without a word of warning.
+      def valid_languages(value)
+        unless value.is_a?(Array) && value.all?(Symbol)
+          invalid!(:"offensive.languages", value, "a list of locale symbols, like %i[en es]")
+        end
+        unknown = value - Data.available_locales
+        if unknown.any?
+          raise ConfigurationError, "offensive.languages has no word list for #{unknown.first.inspect} " \
+                                    "(available: #{Data.available_locales.map(&:inspect).join(', ')})"
+        end
+
+        value.uniq.freeze
+      end
+
+      # :moderate (a no-op unless the moderate gem is loaded) or any callable
+      # that takes the name.
+      def valid_adapters(value)
+        unless value.is_a?(Array) && value.all? { |adapter| adapter == :moderate || adapter.respond_to?(:call) }
+          invalid!(:"offensive.adapters", value, "a list of :moderate or callables, like [:moderate]")
+        end
+
+        value.dup.freeze
+      end
+
+      # nil detects the name from the Rails application; false opts out; a
+      # String names it explicitly (an app whose brand is not its module name).
+      def valid_app_name(value)
+        valid = value.nil? || value == false || (value.is_a?(String) && !value.strip.empty?)
+        invalid!(:app_name, value, "a String, false to opt out, or nil to detect it") unless valid
+
+        value
+      end
+
+      def valid_unique_index(value)
+        valid = value.nil? || ((value.is_a?(String) || value.is_a?(Symbol)) && !value.empty?)
+        invalid!(:unique_index, value, "the name of an index, or nil") unless valid
+
+        value
+      end
+
+      def settings(name, value, names)
+        invalid!(name, value, "a Hash of #{names.join(', ')}") unless value.is_a?(Hash)
+        unknown = value.keys - names
+        raise ConfigurationError, "unknown option #{name}.#{unknown.first} (known: #{names.join(', ')})" if unknown.any?
+
+        value
+      end
+
+      def invalid!(name, value, expectation)
+        raise ConfigurationError, "#{name} must be #{expectation} (got #{value.inspect})"
+      end
+    end
+  end
+end