floss_funding 1.0.0.pre.alpha.1

data/lib/floss_funding/check.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# std libs
+require "openssl"
+
+module FlossFunding
+  # This module loads inside an anonymous module on Ruby 3.1+.
+  # This is why FlossFunding herein uses top-level namespace as `::FlossFunding`.
+  module Check
+    # When this module is included, extend the target with class-level helpers
+    # and set the deterministic time source (used in specs via Timecop).
+    #
+    # @param base [Module] the including module
+    # @param now [Time] the current time (defaults to Time.now)
+    # @return [void]
+    def self.included(base, now = Time.now)
+      base.extend(ClassMethods)
+      ClassMethods.now_time = now
+    end
+
+    # When this module is extended, also extend with class-level helpers and
+    # set the deterministic time source.
+    #
+    # @param base [Module] the extending module
+    # @param now [Time] the current time (defaults to Time.now)
+    # @return [void]
+    def self.extended(base, now = Time.now)
+      base.extend(ClassMethods)
+      ClassMethods.now_time = now
+    end
+
+    # Class-level API used by FlossFunding::Poke to perform activation checks
+    # and generate user-facing messages. Methods here are intended for inclusion
+    # into client libraries when they `extend FlossFunding::Check`.
+    module ClassMethods
+      class << self
+        # Time source used for month arithmetic and testing.
+        # @return [Time]
+        attr_accessor :now_time
+      end
+
+      # Decrypts a hex-encoded activation key using a namespace-derived key.
+      #
+      # @param activation_key [String] 64-character hex string for paid activation
+      # @param namespace [String] the namespace used to derive the cipher key
+      # @return [String, false] plaintext activation key (base word) on success; false if empty
+      def floss_funding_decrypt(activation_key, namespace)
+        return false if activation_key.empty?
+
+        cipher = OpenSSL::Cipher.new("aes-256-cbc").decrypt
+        cipher.key = Digest::MD5.hexdigest(namespace)
+        s = [activation_key].pack("H*")
+
+        cipher.update(s) + cipher.final
+      end
+
+      # Returns true for unpaid or opted-out activation_key that
+      # should not emit any console output (silent success).
+      # Otherwise false.
+      #
+      # @param activation_key [String]
+      # @param namespace [String]
+      # @return [Boolean]
+      def check_unpaid_silence(activation_key, namespace)
+        case activation_key
+        when ::FlossFunding::FREE_AS_IN_BEER, ::FlossFunding::BUSINESS_IS_NOT_GOOD_YET, "#{::FlossFunding::NOT_FINANCIALLY_SUPPORTING}-#{namespace}"
+          # Configured as unpaid
+          true
+        else
+          # Might be configured as paid
+          false
+        end
+      end
+
+      # Returns the list of valid plain text base words for the current month window.
+      #
+      # @return [Array<String>]
+      def base_words
+        ::FlossFunding.base_words(num_valid_words_for_month)
+      end
+
+      # Checks whether the given plaintext matches a valid plaintext base word.
+      #
+      # @param plain_text [String]
+      # @return [Boolean]
+      def check_activation(plain_text)
+        words = base_words
+        # Use fast binary search when available (Ruby >= 2.0), else fall back to include?
+        # We can't run CI on Ruby < 2.3 so the alternate branch is not going to have test coverage.
+        # :nocov:
+        if words.respond_to?(:bsearch)
+          !!words.bsearch { |word| plain_text == word }
+        else
+          words.include?(plain_text)
+        end
+        # :nocov:
+      end
+
+      # Entry point for activation key evaluation and output behavior.
+      #
+      # @param activation_key [String] value from ENV
+      # @param namespace [String] this activation key is valid for a specific namespace; can cover multiple projects / gems
+      # @param env_var_name [String] the ENV variable name checked
+      # @return [void]
+      def floss_funding_initiate_begging(activation_key, namespace, env_var_name)
+        if activation_key.empty?
+          # No activation key provided
+          ::FlossFunding.add_unactivated(namespace)
+          return start_begging(namespace, env_var_name)
+        end
+
+        # A silent short circuit for valid unpaid activations
+        if check_unpaid_silence(activation_key, namespace)
+          ::FlossFunding.add_activated(namespace)
+          ::FlossFunding.add_activation_occurrence(namespace)
+          return
+        end
+
+        valid_activation_hex = !!(activation_key =~ ::FlossFunding::HEX_LICENSE_RULE)
+        unless valid_activation_hex
+          # Invalid activation key format
+          ::FlossFunding.add_unactivated(namespace)
+          return start_coughing(activation_key, namespace, env_var_name)
+        end
+
+        # decrypt the activation key for this namespace
+        plain_text = floss_funding_decrypt(activation_key, namespace)
+
+        # A silent short circuit for valid paid activation keys
+        if check_activation(plain_text)
+          ::FlossFunding.add_activated(namespace)
+          ::FlossFunding.add_activation_occurrence(namespace)
+          return
+        end
+
+        # No valid activation key found
+        ::FlossFunding.add_unactivated(namespace)
+        start_begging(namespace, env_var_name)
+      end
+
+      private
+
+      # Using the month gem to easily do month math.
+      #
+      # @return [Integer] number of valid words based on the month offset
+      def num_valid_words_for_month
+        now_month - ::FlossFunding::START_MONTH
+      end
+
+      # Returns the Month integer for the configured time source.
+      #
+      # @return [Integer]
+      def now_month
+        Month.new(ClassMethods.now_time.year, ClassMethods.now_time.month).to_i
+      end
+
+      # Emits a diagnostic message for invalid activation key format.
+      #
+      # @param activation_key [String]
+      # @param namespace [String]
+      # @param env_var_name [String]
+      # @return [void]
+      def start_coughing(activation_key, namespace, env_var_name)
+        puts <<-COUGHING
+==============================================================
+COUGH, COUGH.
+Ahem, it appears as though you tried to set an activation key
+for #{namespace}, but it was invalid.
+
+  Current (Invalid) Activation Key: #{activation_key}
+  Namespace: #{namespace}
+  ENV Variable: #{env_var_name}
+
+Paid activation keys are 8 bytes, 64 hex characters, long.
+Unpaid activation keys have varying lengths, depending on type and namespace.
+Yours is #{activation_key.length} characters long, and doesn't match any paid or unpaid keys.
+
+Please unset the current ENV variable #{env_var_name}, since it is invalid.
+
+Then find the correct one, or get a new one @ https://floss-funding.dev and set it.
+
+#{FlossFunding::FOOTER}
+        COUGHING
+      end
+
+      # Emits the standard friendly funding message for unactivated usage.
+      #
+      # @param namespace [String]
+      # @param env_var_name [String]
+      # @return [void]
+      def start_begging(namespace, env_var_name)
+        # During load, only emit a single-line note and defer the large blurb to at_exit
+        puts %(FLOSS Funding: Activation key missing for #{namespace}. Set ENV[#{env_var_name}] to activation key; details will be shown at exit.)
+      end
+    end
+  end
+end

data/lib/floss_funding/config.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "rubygems" # For Gem::Specification
+
+module FlossFunding
+  # Handles configuration loading from a .floss_funding.yml file located at the
+  # root of the including project (heuristically discovered by walking upward
+  # from the including file path until a Gemfile or *.gemspec is found).
+  #
+  # All APIs in this module require the including file path (e.g., `__FILE__`).
+  #
+  # The loaded config is merged over DEFAULT_CONFIG, so any unspecified keys fall
+  # back to defaults.
+  module Config
+    # The file name to look for in the project root.
+    # @return [String]
+    CONFIG_FILE_NAME = ".floss_funding.yml"
+
+    # Default configuration values for FlossFunding prompting.
+    # Also includes slots for gemspec-derived attributes we track per gem.
+    # @return [Hash{String=>Object}]
+    DEFAULT_CONFIG = {
+      "suggested_donation_amount" => [5],
+      "floss_funding_url" => ["https://floss-funding.dev"],
+      # Optional namespace override for when including without explicit namespace
+      # When set (non-empty string), this will be used as the namespace instead of the including module's name
+      "namespace" => [],
+      # Track both the base.name namespace(s) and any custom namespace(s) passed to Poke.new
+      "base_namespaces" => [],
+      "custom_namespaces" => [],
+      # Gemspec-derived attributes (nil when unknown)
+      "gem_name" => [],
+      "homepage" => [],
+      "authors" => [],
+      "funding_uri" => [],
+    }.freeze
+
+    class << self
+      # Loads configuration from .floss_funding.yml by walking up from the
+      # provided including file path to discover the project root.
+      #
+      # @param including_path [String] the including file path (e.g., __FILE__)
+      # @return [Hash{String=>Object}] configuration hash with defaults merged
+      # @raise [::FlossFunding::Error] if including_path is not a String
+      def load_config(including_path)
+        unless including_path.is_a?(String)
+          raise ::FlossFunding::Error, "including must be a String file path (e.g., __FILE__), got #{including_path.class}"
+        end
+
+        # Discover project root (Gemfile or *.gemspec)
+        project_root = find_project_root(including_path)
+
+        # Load YAML config if present (respect test stubs of find_config_file)
+        config_file = find_config_file(including_path)
+        raw_config = config_file ? load_yaml_file(config_file) : {}
+
+        # Strict filter: only allow known string keys, then normalize to arrays
+        filtered = {}
+        raw_config.each do |k, v|
+          next unless k.is_a?(String)
+          next unless DEFAULT_CONFIG.key?(k)
+          filtered[k] = normalize_to_array(v)
+        end
+
+        # Load gemspec data for defaults if available
+        gemspec_data = project_root ? read_gemspec_data(project_root) : {}
+        # Prepare defaults from gemspec:
+        # - Store all gemspec attributes into config slots, as arrays
+        # - If floss_funding_url not set in YAML, default to gemspec funding_uri
+        gemspec_defaults = {}
+        unless gemspec_data.empty?
+          gemspec_defaults["gem_name"] = normalize_to_array(gemspec_data[:name]) # name is required by rubygems
+          gemspec_defaults["homepage"] = normalize_to_array(gemspec_data[:homepage]) if gemspec_data[:homepage]
+          gemspec_defaults["authors"] = normalize_to_array(gemspec_data[:authors]) # authors defaults to []
+          gemspec_defaults["funding_uri"] = normalize_to_array(gemspec_data[:funding_uri]) if gemspec_data[:funding_uri]
+          if gemspec_data[:funding_uri] && !filtered.key?("floss_funding_url")
+            gemspec_defaults["floss_funding_url"] = normalize_to_array(gemspec_data[:funding_uri])
+          end
+        end
+
+        # Merge precedence: DEFAULT < gemspec_defaults, with filtered_yaml overriding entirely when present
+        merged = {}
+        DEFAULT_CONFIG.keys.each do |key|
+          if filtered.key?(key)
+            # YAML-provided known string keys take full precedence (override defaults and gemspec values)
+            merged[key] = Array(filtered[key]).compact.flatten.uniq
+          else
+            # Otherwise, start from defaults and enrich with gemspec-derived values when available
+            merged[key] = []
+            merged[key].concat(Array(DEFAULT_CONFIG[key]))
+            merged[key].concat(Array(gemspec_defaults[key])) if gemspec_defaults.key?(key)
+            merged[key] = merged[key].compact.flatten.uniq
+          end
+        end
+        merged
+      end
+
+      private
+
+      # Finds the configuration file by walking up from including_path looking for
+      # a .floss_funding.yml file. This works for gems, Bundler projects, and
+      # plain Ruby projects without Gemfile/gemspec.
+      #
+      # @param including_path [String] the including file path
+      # @return [String, nil] absolute path to the config file or nil if not found
+      def find_config_file(including_path)
+        begin
+          start_dir = File.dirname(File.expand_path(including_path))
+          current_dir = start_dir
+
+          # Determine an upper boundary for search to avoid leaking configs from unrelated parents.
+          project_root = find_project_root(including_path)
+
+          # Prefer the directory that looks like the local project root (parent of lib)
+          lib_root = (File.basename(start_dir) == "lib") ? File.dirname(start_dir) : nil
+
+          boundary_dir = lib_root || project_root
+
+          # If we couldn't determine any reasonable boundary (very unusual), limit the
+          # search to the including file's directory and its immediate parent. This
+          # still allows patterns like lib/... including a config placed at the
+          # project root (parent of lib), while preventing accidental pickup of
+          # higher-level fixture/config files.
+          if boundary_dir.nil?
+            parent_once = File.dirname(start_dir)
+            while current_dir && current_dir != "/"
+              candidate = File.join(current_dir, CONFIG_FILE_NAME)
+              return candidate if File.exist?(candidate)
+              break if current_dir == parent_once
+              current_dir = File.dirname(current_dir)
+            end
+            return
+          end
+
+          # Search upward until the boundary (inclusive)
+          while current_dir && current_dir != "/"
+            candidate = File.join(current_dir, CONFIG_FILE_NAME)
+            return candidate if File.exist?(candidate)
+            break if current_dir == boundary_dir
+            current_dir = File.dirname(current_dir)
+          end
+        rescue
+          # Fall through to nil when any unexpected error happens
+        end
+        nil
+      end
+
+      # Attempts to find the root directory of the project that included
+      # FlossFunding::Poke by starting from the including file path and walking
+      # up the directory tree until a Gemfile or *.gemspec is found.
+      #
+      # @param including_path [String] the including file path
+      # @return [String, nil] the discovered project root directory or nil
+      def find_project_root(including_path)
+        begin
+          current_dir = File.dirname(File.expand_path(including_path))
+          while current_dir && current_dir != "/"
+            return current_dir if Dir.glob(File.join(current_dir, "*.gemspec")).any? || File.exist?(File.join(current_dir, "Gemfile"))
+            current_dir = File.dirname(current_dir)
+          end
+        rescue
+          nil
+        end
+        nil
+      end
+
+      # Loads and parses a YAML file from disk.
+      #
+      # @param file_path [String] absolute path to the YAML file
+      # @return [Hash] parsed YAML content or empty hash if parsing fails
+      def load_yaml_file(file_path)
+        begin
+          YAML.load_file(file_path) || {}
+        rescue
+          # If there's any error loading the file, return an empty hash
+          {}
+        end
+      end
+
+      # Reads gemspec data from the first *.gemspec in project_root using
+      # RubyGems API, and extracts fields of interest.
+      # @param project_root [String]
+      # @return [Hash] keys: :name, :homepage, :authors, :funding_uri
+      def read_gemspec_data(project_root)
+        gemspec_path = Dir.glob(File.join(project_root, "*.gemspec")).first
+        return {} unless gemspec_path
+        begin
+          spec = Gem::Specification.load(gemspec_path)
+          return {} unless spec
+          metadata = spec.metadata || {}
+          funding_uri = metadata["funding_uri"] || metadata[:funding_uri]
+          {
+            :name => spec.name,
+            :homepage => spec.homepage,
+            :authors => spec.authors,
+            :funding_uri => funding_uri,
+          }
+        rescue StandardError
+          {}
+        end
+      end
+
+      # Normalize a value from YAML or gemspec to an array.
+      # - nil => []
+      # - array => same array
+      # - scalar => [scalar]
+      def normalize_to_array(value)
+        return [] if value.nil?
+        return value.compact if value.is_a?(Array)
+        [value]
+      end
+    end
+  end
+end

data/lib/floss_funding/poke.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module FlossFunding
+  # Public API for including FlossFunding into your library/module.
+  #
+  # Usage patterns:
+  #
+  # 1. Traditional namespace (uses the including module's name):
+  #
+  #     module MyGemLibrary
+  #       include FlossFunding::Poke.new(__FILE__)
+  #     end
+  #
+  # 2. Arbitrary custom namespace (can add version, or anything else):
+  #
+  #     module MyGemLibrary
+  #       include FlossFunding::Poke.new(__FILE__, "Custom::Namespace::V4")
+  #     end
+  #
+  # In all cases, the first parameter must be a String file path (e.g., `__FILE__`).
+  module Poke
+    # Use class << self for defining class methods
+    class << self
+      # Hook invoked when including FlossFunding::Poke directly.
+      #
+      # Direct inclusion is not supported; always use `Poke.new(__FILE__, ...)`.
+      #
+      # @param base [Module] the target including module
+      # @raise [::FlossFunding::Error] always, instructing correct usage
+      def included(base)
+        raise ::FlossFunding::Error, "Do not include FlossFunding::Poke directly. Use include FlossFunding::Poke.new(__FILE__, optional_namespace, optional_env_prefix)."
+      end
+
+      # Builds a module suitable for inclusion which sets up FlossFunding.
+      #
+      # @param including_path [String] the including file path (e.g., `__FILE__`)
+      # @param namespace [String, nil] optional custom namespace for activation key
+      # @param env_prefix [String, nil] optional ENV var prefix; defaults to
+      #   FlossFunding::UnderBar::DEFAULT_PREFIX when nil
+      # @return [Module] a module that can be included into your namespace
+      def new(including_path, namespace = nil, env_prefix = nil)
+        Module.new do
+          define_singleton_method(:included) do |base|
+            FlossFunding::Poke.setup_begging(base, namespace, env_prefix, including_path)
+          end
+        end
+      end
+
+      # Performs common setup: extends the base with Check, computes the
+      # namespace and ENV var name, loads configuration, and initiates begging.
+      #
+      # @param base [Module] the module including the returned Poke module
+      # @param custom_namespace [String, nil] custom namespace or nil to use base.name
+      # @param env_prefix [String, nil] ENV var prefix or default when nil
+      # @param including_path [String] source file path of base (e.g., `__FILE__`)
+      # @return [void]
+      # @raise [::FlossFunding::Error] if including_path is not a String
+      # @raise [::FlossFunding::Error] if base.name is not a String
+      def setup_begging(base, custom_namespace, env_prefix, including_path)
+        unless including_path.is_a?(String)
+          raise ::FlossFunding::Error, "including_path must be a String file path (e.g., __FILE__), got #{including_path.class}"
+        end
+        unless base.respond_to?(:name) && base.name && base.name.is_a?(String)
+          raise ::FlossFunding::Error, "base must have a name (e.g., MyGemLibrary), got #{base.inspect}"
+        end
+
+        require "floss_funding/check"
+        # Extend the base with the checker module first
+        base.extend(::FlossFunding::Check)
+
+        # Load configuration from .floss_funding.yml if it exists
+        config = ::FlossFunding::Config.load_config(including_path)
+
+        # Three data points needed:
+        # 1. namespace (derived from the base class name, config, or param)
+        # 2. ENV variable name (derived from namespace)
+        # 3. activation key (derived from ENV variable)
+        namespace =
+          if custom_namespace && !custom_namespace.empty?
+            custom_namespace
+          else
+            base.name
+          end
+
+        # Track both base.name and the custom namespace (if provided) in the configuration arrays
+        config["base_namespaces"] ||= []
+        config["base_namespaces"] << base.name
+        config["custom_namespaces"] ||= []
+        config["custom_namespaces"] << custom_namespace if custom_namespace && !custom_namespace.empty?
+        # Deduplicate
+        config["base_namespaces"] = config["base_namespaces"].flatten.uniq
+        config["custom_namespaces"] = config["custom_namespaces"].flatten.uniq
+
+        env_var_name = ::FlossFunding::UnderBar.env_variable_name(
+          {
+            :prefix => env_prefix,
+            :namespace => namespace,
+          },
+        )
+        activation_key = ENV.fetch(env_var_name, "")
+
+        # Store configuration and ENV var name under the effective namespace
+        ::FlossFunding.set_configuration(namespace, config)
+        ::FlossFunding.set_env_var_name(namespace, env_var_name)
+
+        # Now call the begging method after extending
+        base.floss_funding_initiate_begging(activation_key, namespace, env_var_name)
+      end
+    end
+  end
+end

data/lib/floss_funding/under_bar.rb

@@ -0,0 +1,57 @@
+module FlossFunding
+  # Utilities to convert Ruby namespaces to safe, uppercased, underscore forms
+  # for environment variable names. Protects against malicious or invalid class
+  # names via conservative character rules.
+  #
+  # See also: https://github.com/galtzo-floss/shields-badge/blob/main/lib/shields/badge.rb
+  module UnderBar
+    # Default ENV prefix used when none is provided.
+    # @return [String]
+    DEFAULT_PREFIX = "FLOSS_FUNDING_"
+
+    # Allowed characters for a single namespace segment. Max length 256 to avoid abuse.
+    # @return [Regexp]
+    SAFE_TO_UNDERSCORE = /\A[\p{UPPERCASE-LETTER}\p{LOWERCASE-LETTER}\p{DECIMAL-NUMBER}]{1,256}\Z/
+
+    # Pattern to insert underscores before capital letters.
+    # @return [Regexp]
+    SUBBER_UNDER = /(\p{UPPERCASE-LETTER})/
+
+    # Pattern for a leading underscore to be removed after transformation.
+    # @return [Regexp]
+    INITIAL_UNDERSCORE = /^_/
+
+    class << self
+      # Builds an uppercased ENV variable name from a Ruby namespace.
+      #
+      # @param opts [Hash]
+      # @option opts [String] :namespace (required) the Ruby namespace (e.g., "My::Lib")
+      # @option opts [String] :prefix optional ENV name prefix (defaults to DEFAULT_PREFIX)
+      # @return [String] the resulting ENV variable name
+      # @raise [FlossFunding::Error] when :namespace is not a String or contains invalid characters
+      def env_variable_name(opts = {})
+        namespace = opts[:namespace]
+        prefix = opts[:prefix] || DEFAULT_PREFIX
+        raise FlossFunding::Error, "namespace must be a String, but is #{namespace.class}" unless namespace.is_a?(String)
+
+        name_parts = namespace.split("::")
+        env_name = name_parts.map { |np| to_under_bar(np) }.join("_")
+        "#{prefix}#{env_name}".upcase
+      end
+
+      # Converts a single namespace segment to an underscored, uppercased string.
+      #
+      # @param string [String] the namespace segment to convert
+      # @return [String] an uppercased, underscore-separated representation
+      # @raise [FlossFunding::Error] when the string contains invalid characters or is too long
+      def to_under_bar(string)
+        safe = string[SAFE_TO_UNDERSCORE]
+        raise FlossFunding::Error, "Invalid! Each part of klass name must match #{SAFE_TO_UNDERSCORE}: #{safe} (#{safe.class}) != #{string[0..255]} (#{string.class})" unless safe == string.to_s
+
+        underscored = safe.gsub(SUBBER_UNDER) { "_#{$1}" }
+        shifted_leading_underscore = underscored.sub(INITIAL_UNDERSCORE, "")
+        shifted_leading_underscore.upcase
+      end
+    end
+  end
+end

data/lib/floss_funding/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module FlossFunding
+  # Version information for the FlossFunding gem.
+  module Version
+    # The current gem version.
+    # @return [String]
+    VERSION = "1.0.0-alpha.1"
+  end
+end