api_keys 0.2.1 → 0.4.0

data/lib/api_keys/form_builder_extensions.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  # Opt-in form builder extensions for API key forms.
+  #
+  # These helpers reduce boilerplate while letting you control the styling.
+  # Include them in your form builder to use:
+  #
+  #   # In config/initializers/api_keys.rb:
+  #   Rails.application.config.to_prepare do
+  #     ActionView::Helpers::FormBuilder.include(ApiKeys::FormBuilderExtensions)
+  #   end
+  #
+  # @example Expiration select
+  #   <%= form.api_key_expiration_select(class: "my-select-class") %>
+  #
+  # @example Scopes checkboxes with block for custom rendering
+  #   <%= form.api_key_scopes_checkboxes(@scopes) do |scope, checked| %>
+  #     <label>
+  #       <%= check_box_tag "api_key[scopes][]", scope, checked, class: "my-checkbox" %>
+  #       <%= scope %>
+  #     </label>
+  #   <% end %>
+  #
+  module FormBuilderExtensions
+    # Renders a select field for API key expiration presets.
+    #
+    # @param options [Hash] Options passed to the select helper
+    # @param html_options [Hash] HTML attributes for the select element
+    # @return [String] HTML select element
+    #
+    # @example Basic usage
+    #   <%= form.api_key_expiration_select %>
+    #
+    # @example With Tailwind classes
+    #   <%= form.api_key_expiration_select(class: "w-full px-4 py-3 border rounded-lg") %>
+    #
+    # @example With custom default
+    #   <%= form.api_key_expiration_select(selected: "30_days") %>
+    #
+    def api_key_expiration_select(options = {}, html_options = {})
+      # expires_at_preset is a form-only param, not a model attribute
+      # So we only use the provided :selected option or default
+      selected = options.delete(:selected) || ApiKeys::ExpirationOptions.default_value
+
+      select(
+        :expires_at_preset,
+        @template.options_for_select(ApiKeys::ExpirationOptions.for_select, selected),
+        options,
+        html_options
+      )
+    end
+
+    # Renders checkboxes for API key scopes.
+    #
+    # If a block is given, yields each scope and its checked state for custom rendering.
+    # If no block is given, returns an array of checkbox data for manual iteration.
+    #
+    # @param scopes [Array<String>] Available scopes to render
+    # @param checked [Symbol, Array] Which scopes should be checked:
+    #   - :all (default for new records) - all scopes checked
+    #   - :none - no scopes checked
+    #   - Array - specific scopes to check
+    #   - nil - uses the object's current scopes
+    # @return [String, Array] HTML if block given, otherwise array of scope data
+    #
+    # @example With block (recommended for custom styling)
+    #   <%= form.api_key_scopes_checkboxes(@scopes) do |scope, checked| %>
+    #     <label class="flex items-center gap-2">
+    #       <%= check_box_tag "api_key[scopes][]", scope, checked, class: "rounded" %>
+    #       <code><%= scope %></code>
+    #     </label>
+    #   <% end %>
+    #
+    # @example Simple rendering without block
+    #   <% form.api_key_scopes_checkboxes(@scopes).each do |scope_data| %>
+    #     <%= check_box_tag "api_key[scopes][]", scope_data[:value], scope_data[:checked] %>
+    #     <%= scope_data[:value] %>
+    #   <% end %>
+    #
+    def api_key_scopes_checkboxes(scopes, checked: nil, &block)
+      # Determine which scopes should be checked
+      checked_scopes = resolve_checked_scopes(scopes, checked)
+
+      scope_data = scopes.map do |scope|
+        {
+          value: scope,
+          checked: checked_scopes.include?(scope),
+          field_name: "#{object_name}[scopes][]"
+        }
+      end
+
+      if block_given?
+        # Yield each scope for custom rendering
+        safe_buffer = ActiveSupport::SafeBuffer.new
+        scope_data.each do |data|
+          safe_buffer << @template.capture { yield(data[:value], data[:checked]) }
+        end
+        safe_buffer
+      else
+        # Return raw data for manual iteration
+        scope_data
+      end
+    end
+
+    # Returns structured data for building a token display UI.
+    # Useful when you need to build a custom token display with copy functionality.
+    #
+    # @return [Hash] Token display data with keys:
+    #   - :masked [String] The masked token (e.g., "sk_live_••••abc")
+    #   - :full [String, nil] The full token (only for viewable public keys)
+    #   - :viewable [Boolean] Whether the full token can be displayed
+    #   - :type [Symbol, String, nil] A known built-in type is a Symbol; custom
+    #     untrusted values remain Strings so they are never interned as Symbols.
+    #   - :environment [String, nil] The environment (e.g., "live", "test")
+    #
+    # @example
+    #   <% data = form.api_key_token_data %>
+    #   <code><%= data[:masked] %></code>
+    #   <% if data[:viewable] %>
+    #     <button data-token="<%= data[:full] %>">Copy</button>
+    #   <% end %>
+    #
+    def api_key_token_data
+      return {} unless object.respond_to?(:masked_token)
+
+      {
+        masked: object.masked_token,
+        full: object.viewable_token,
+        viewable: object.respond_to?(:public_key_type?) && object.public_key_type?,
+        type: safe_key_type(object.key_type),
+        environment: object.environment
+      }
+    end
+
+    private
+
+    def safe_key_type(value)
+      case value.to_s
+      when "publishable" then :publishable
+      when "secret" then :secret
+      when "" then nil
+      else value.to_s
+      end
+    end
+
+    def resolve_checked_scopes(scopes, checked)
+      case checked
+      when :all
+        scopes.map(&:to_s)
+      when :none
+        []
+      when Array
+        checked.map(&:to_s)
+      when nil
+        # For new records, default to all checked
+        # For existing records, use the object's scopes
+        if object&.persisted?
+          (object.scopes || []).map(&:to_s)
+        else
+          scopes.map(&:to_s)
+        end
+      else
+        scopes.map(&:to_s)
+      end
+    end
+  end
+end

data/lib/api_keys/helpers/expiration_options.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  module Helpers
+    # Helper for handling API key expiration presets.
+    #
+    # Provides a consistent set of expiration options for use in forms,
+    # and parsing logic to convert preset strings to actual dates.
+    #
+    # @example In your view (form select)
+    #   <%= form.select :expires_at_preset,
+    #       ApiKeys::Helpers::ExpirationOptions.for_select %>
+    #
+    # @example In your controller
+    #   expires_at = ApiKeys::Helpers::ExpirationOptions.parse(params[:expires_at_preset])
+    #   @api_key = current_org.create_api_key!(expires_at: expires_at, ...)
+    #
+    class ExpirationOptions
+      # Default preset options with human-readable labels
+      DEFAULT_PRESETS = [
+        { label: "No Expiration", value: "no_expiration", days: nil },
+        { label: "7 days", value: "7_days", days: 7 },
+        { label: "30 days", value: "30_days", days: 30 },
+        { label: "60 days", value: "60_days", days: 60 },
+        { label: "90 days", value: "90_days", days: 90 },
+        { label: "1 year", value: "365_days", days: 365 }
+      ].map(&:freeze).freeze
+
+      class << self
+        # Returns options suitable for a Rails select helper.
+        #
+        # @param include_no_expiration [Boolean] Whether to include "No Expiration" option (default: true)
+        # @param presets [Array<Integer>, nil] Custom list of days to include (e.g., [7, 30, 90])
+        #   If nil, uses DEFAULT_PRESETS
+        # @return [Array<Array>] Array of [label, value] pairs for select helper
+        #
+        # @example Default options
+        #   ExpirationOptions.for_select
+        #   # => [["No Expiration", "no_expiration"], ["7 days", "7_days"], ...]
+        #
+        # @example Custom presets
+        #   ExpirationOptions.for_select(presets: [7, 30, 365])
+        #   # => [["No Expiration", "no_expiration"], ["7 days", "7_days"], ["30 days", "30_days"], ["1 year", "365_days"]]
+        #
+        # @example Without "No Expiration"
+        #   ExpirationOptions.for_select(include_no_expiration: false)
+        #   # => [["7 days", "7_days"], ["30 days", "30_days"], ...]
+        #
+        def for_select(include_no_expiration: true, presets: nil)
+          options = if presets
+                      build_custom_presets(presets, include_no_expiration)
+                    else
+                      filter_default_presets(include_no_expiration)
+                    end
+
+          options.map { |opt| [opt[:label], opt[:value]] }
+        end
+
+        # Parse an expiration preset string into an actual datetime.
+        #
+        # @param preset [String, nil] The preset value (e.g., "30_days", "no_expiration")
+        # @return [ActiveSupport::TimeWithZone, nil] The expiration date, or nil for no expiration
+        #
+        # @example
+        #   ExpirationOptions.parse("30_days")  # => 30.days.from_now
+        #   ExpirationOptions.parse("no_expiration")  # => nil
+        #   ExpirationOptions.parse(nil)  # => nil
+        #   ExpirationOptions.parse("invalid")  # => raises ArgumentError
+        #
+        def parse(preset)
+          return nil if preset.nil? || preset == ""
+          unless preset.is_a?(String) && preset.valid_encoding? && preset.bytesize <= 32
+            raise ArgumentError, "Invalid API key expiration preset"
+          end
+          return nil if preset.blank? || preset == "no_expiration"
+
+          # Try to extract days from the preset string (e.g., "30_days" => 30)
+          if preset =~ /\A(\d+)_days?\z/
+            days = ::Regexp.last_match(1).to_i
+            # Reasonable max: ~10 years to prevent overflow issues
+            return days.days.from_now if days.positive? && days <= 3650
+          end
+
+          # Check against known presets
+          known = DEFAULT_PRESETS.find { |p| p[:value] == preset }
+          return known[:days].days.from_now if known && known[:days]
+
+          raise ArgumentError, "Invalid API key expiration preset"
+        end
+
+        # Returns the default preset value (useful for form defaults)
+        #
+        # @return [String] The default preset value
+        def default_value
+          "no_expiration"
+        end
+
+        private
+
+        def filter_default_presets(include_no_expiration)
+          if include_no_expiration
+            DEFAULT_PRESETS
+          else
+            DEFAULT_PRESETS.reject { |p| p[:value] == "no_expiration" }
+          end
+        end
+
+        def build_custom_presets(days_list, include_no_expiration)
+          unless days_list.is_a?(Array) && days_list.all? { |days| days.is_a?(Integer) && days.between?(1, 3650) }
+            raise ArgumentError, "Expiration presets must be an array of integers between 1 and 3650"
+          end
+
+          options = []
+
+          if include_no_expiration
+            options << { label: "No Expiration", value: "no_expiration", days: nil }
+          end
+
+          days_list.each do |days|
+            options << preset_for_days(days)
+          end
+
+          options
+        end
+
+        def preset_for_days(days)
+          label = case days
+                  when 1 then "1 day"
+                  when 365 then "1 year"
+                  when ->(d) { d % 365 == 0 } then "#{days / 365} years"
+                  else "#{days} days"
+                  end
+
+          { label: label, value: "#{days}_days", days: days }
+        end
+      end
+    end
+  end
+end

data/lib/api_keys/helpers/token_session.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+require "active_support/message_encryptor"
+require "json"
+
+module ApiKeys
+  module Helpers
+    # Helper for managing API key tokens in the session.
+    #
+    # Secret keys can only be shown once (immediately after creation) because
+    # the plaintext token is not stored in the database. This helper provides
+    # a clean interface for the "show token once" pattern:
+    #
+    # 1. After creating a key, store an encrypted, short-lived handoff in the session
+    # 2. On the success page, decrypt, retrieve, and clear the token
+    # 3. If the user refreshes, the token is gone
+    #
+    # @example In your controller
+    #   # After creating a key:
+    #   def create
+    #     @api_key = current_org.create_api_key!(...)
+    #     ApiKeys::Helpers::TokenSession.store(session, @api_key)
+    #     redirect_to success_path
+    #   end
+    #
+    #   # On the success page:
+    #   def success
+    #     @token = ApiKeys::Helpers::TokenSession.retrieve_once(session)
+    #     redirect_to index_path, alert: "Token already shown" unless @token
+    #   end
+    #
+    class TokenSession
+      # Default session key for storing the token
+      DEFAULT_SESSION_KEY = :api_keys_new_token
+      MAX_TOKEN_BYTESIZE = 512
+      MAX_CIPHERTEXT_BYTESIZE = 4096
+      MAX_KEY_ID_BYTESIZE = 128
+      HANDOFF_VERSION = 2
+      HANDOFF_TTL = 10.minutes
+      ENCRYPTION_CIPHER = "aes-256-gcm"
+      ENCRYPTION_SALT = "api_keys/token_session/v2"
+      ENCRYPTION_PURPOSE = "api_keys.token_session"
+      JSON_SERIALIZER = Module.new do
+        module_function
+
+        def dump(value)
+          JSON.generate(value)
+        end
+
+        def load(value)
+          JSON.parse(value)
+        end
+      end
+
+      class << self
+        # Store an encrypted API key-token handoff in the session for later retrieval.
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param api_key [ApiKeys::ApiKey] The newly created API key
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [String] The token that was stored
+        def store(session, api_key, key: DEFAULT_SESSION_KEY)
+          token = api_key.respond_to?(:token) ? api_key.token : api_key.to_s
+          unless valid_token_payload?(token)
+            raise ArgumentError, "Cannot store an invalid API key token in the session"
+          end
+
+          api_key_id = normalize_api_key_id(api_key.id) if api_key.respond_to?(:id)
+          encrypted_payload = token_encryptor.encrypt_and_sign(
+            { "token" => token, "api_key_id" => api_key_id },
+            expires_in: HANDOFF_TTL,
+            purpose: ENCRYPTION_PURPOSE
+          )
+          session[key] = {
+            "version" => HANDOFF_VERSION,
+            "ciphertext" => encrypted_payload,
+            "api_key_id" => api_key_id
+          }
+          token
+        end
+
+        # Retrieve and clear the token from the session.
+        # Returns nil if no token is stored (e.g., page was refreshed).
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [String, nil] The token, or nil if not present
+        def retrieve_once(session, key: DEFAULT_SESSION_KEY, api_key: nil, api_key_id: nil)
+          payload = session.delete(key)
+          expected_id = normalize_api_key_id(api_key_id || (api_key.id if api_key.respond_to?(:id)))
+
+          # Plain string payloads from older versions remain readable only when
+          # the caller does not request ID binding.
+          return payload if expected_id.nil? && valid_token_payload?(payload)
+          decoded_payload = decode_payload(payload)
+          return nil unless decoded_payload
+
+          token = decoded_payload["token"] || decoded_payload[:token]
+          stored_id = decoded_payload["api_key_id"] || decoded_payload[:api_key_id]
+          return nil if expected_id && stored_id.to_s != expected_id.to_s
+          return nil unless valid_token_payload?(token)
+
+          token
+        end
+
+        # Check if a token is available in the session without removing it.
+        # Useful for conditional rendering.
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [Boolean] true if a token is stored
+        def available?(session, key: DEFAULT_SESSION_KEY, api_key: nil, api_key_id: nil)
+          payload = session[key]
+          expected_id = normalize_api_key_id(api_key_id || (api_key.id if api_key.respond_to?(:id)))
+
+          return valid_token_payload?(payload) if payload.is_a?(String) && expected_id.nil?
+          decoded_payload = decode_payload(payload)
+          return false unless decoded_payload
+
+          token = decoded_payload["token"] || decoded_payload[:token]
+          stored_id = decoded_payload["api_key_id"] || decoded_payload[:api_key_id]
+          return false if expected_id && stored_id.to_s != expected_id.to_s
+
+          valid_token_payload?(token)
+        end
+
+        private
+
+        def decode_payload(payload)
+          return nil unless payload.is_a?(Hash)
+
+          version_present = payload.key?("version") || payload.key?(:version)
+          return legacy_payload(payload) unless version_present
+
+          version = payload["version"] || payload[:version]
+          return nil unless version == HANDOFF_VERSION
+
+          ciphertext = payload["ciphertext"] || payload[:ciphertext]
+          outer_id = normalize_api_key_id(payload["api_key_id"] || payload[:api_key_id])
+          return nil unless ciphertext.is_a?(String) && ciphertext.bytesize <= MAX_CIPHERTEXT_BYTESIZE
+
+          decoded = token_encryptor.decrypt_and_verify(ciphertext, purpose: ENCRYPTION_PURPOSE)
+          return nil unless decoded.is_a?(Hash)
+
+          inner_id = normalize_api_key_id(decoded["api_key_id"] || decoded[:api_key_id])
+          return nil unless outer_id == inner_id
+
+          decoded
+        rescue ActiveSupport::MessageEncryptor::InvalidMessage, ArgumentError
+          nil
+        end
+
+        def legacy_payload(payload)
+          token = payload["token"] || payload[:token]
+          stored_id = normalize_api_key_id(payload["api_key_id"] || payload[:api_key_id])
+          return nil unless valid_token_payload?(token)
+
+          { "token" => token, "api_key_id" => stored_id }
+        rescue ArgumentError
+          nil
+        end
+
+        def normalize_api_key_id(value)
+          return nil if value.nil?
+
+          normalized = value.to_s
+          valid = normalized.present? && normalized.valid_encoding? &&
+            normalized.bytesize <= MAX_KEY_ID_BYTESIZE &&
+            normalized.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
+          raise ArgumentError, "API key ID is invalid" unless valid
+
+          normalized
+        rescue ArgumentError
+          raise ArgumentError, "API key ID is invalid"
+        end
+
+        def token_encryptor
+          application = Rails.application if defined?(Rails) && Rails.respond_to?(:application)
+          unless application&.respond_to?(:key_generator)
+            raise ArgumentError, "Rails.application.key_generator is required for secure token handoff"
+          end
+
+          key_length = ActiveSupport::MessageEncryptor.key_len(ENCRYPTION_CIPHER)
+          encryption_key = application.key_generator.generate_key(ENCRYPTION_SALT, key_length)
+          ActiveSupport::MessageEncryptor.new(
+            encryption_key,
+            cipher: ENCRYPTION_CIPHER,
+            serializer: JSON_SERIALIZER
+          )
+        end
+
+        def valid_token_payload?(token)
+          token.is_a?(String) && token.present? && token.valid_encoding? &&
+            token.bytesize <= MAX_TOKEN_BYTESIZE &&
+            token.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end