magic_links 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6939cd65d873662c0c1101a1073e1d9dcfef386af25be14aa8d8232a5b293e7
+  data.tar.gz: 437b07e49b311be7721c3e3882275893ce3fe1ce2587105665b0a9e827c8f655
+SHA512:
+  metadata.gz: 0146bba9e94182eb77b5bc001abfb0edcd232ea07fea288868fbdb63c4279676084147abe4da32b91257f91ff0b263b086095d068efdcf72399c934e37525bd5
+  data.tar.gz: 8b5d6a7bfec01316fa1f232d4239838b95a737f2d062c22af3a7ecc5be1b294be90794ee78d3f81ba02cb0631a9afb8f0d57e2e26d38e99de75a8157db455cf8

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 wozza35
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# MagicLinks
+
+Send 'magic links' to your users that grants them authorized access to your application without the need for them to be signed in.
+
+#### Features:
+
+- Grant authorized access to a subset of controllers and actions only
+- Set an expiry time on the magic link
+- Quick and easy to implement via the use of magic link 'templates' and inbuilt url helpers
+- Negligible performance overhead
+
+## Requirements
+This gem assumes you are using Devise for authentication, and already have it installed and configured. If you have not done so, then follow their setup instructions here: https://github.com/heartcombo/devise#getting-started
+
+It also requires that your application is using cookies.
+
+## Installation
+
+1. Add this line to your application's Gemfile:
+
+```ruby
+gem 'magic_links'
+```
+
+2. Install the gem
+```bash
+$ bundle install
+```
+
+3. Copy across the magic link migrations and run them
+```bash
+rails magic_links:install:migrations
+rails db:migrate
+```
+
+4. Add the magic_link authentication strategy to your Devise configuration. For example, to enable magic_link authentication for 'users':
+
+#### /config/initializers/devise.rb:
+```ruby
+config.warden do |manager|
+  # adds magic_token_authentication before the devise defaults
+  manager.default_strategies(scope: :user).unshift :magic_token_authentication
+end
+```
+
+### Usage
+
+To start creating magic links, you first need to specify one or more 'templates'. It is recommended that you do this by creating a magic_links initializer:
+
+#### /config/initializers/magic_links.rb:
+Example:
+```ruby
+# This will enable the helper:
+# `magic_link_for(current_user, :order_tracking, '/orders/12345/tracking')`, which will return a relative path, or
+# `magic_url_for(current_user, :order_tracking, '/orders/12345/tracking')`, which will return a a full URL.
+# the resulting path/URL (e.g. `/ot/abcd12345`) will redirect to `/orders/12345/tracking`,
+# authenticating `current_user` to perform any actions permitted in the `action_scope`. 
+# In this case, the user can call the 'show' and 'edit' actions on the 'Orders::TrackingController' and the 'dashboard'
+# action on 'CustomersController'
+
+Rails.application.config.to_prepare do
+  MagicLinks.add_template(
+      name: :order_tracking,
+      pattern: '/ot/:token',
+      action_scope: {'orders/tracking': [:show, :edit], customers: :dashboard},
+      strength: :mild # mild (8 char strength), moderate (16), or strong (32)
+  )
+ end
+```
+
+The templates can then be used as arguments to the url helpers. For example, to generate a magic link that can be sent 
+to a user:
+
+```ruby
+magic_link_for(current_user, :order_tracking, order_tracking_path, expiry: 1.week.from_now) 
+# will output '/ot/abcd1234'
+```
+
+Note: If a user attempts to perform an action that isn't part of the magic token's scope, they will receive a 401 and, 
+with Devise's default behavior will be redirected to a sign in page.
+
+### Magic Links Helper
+By default, the magic_links helper is included in `ActionController`. If you would like to use the magic_links helpers 
+anywhere else (e.g. in a mailer) then you can simply include the helper manually.
+e.g:
+```ruby
+module UserMailer
+  include MagicLinks::UrlHelper
+  ...
+end
+```
+
+### Default url options
+When using the `magic_url_for` helper you'll need to specify default_url_options for your development and testing
+environments.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MagicLinks'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'

data/app/helpers/magic_links/url_helper.rb

@@ -0,0 +1,27 @@
+module MagicLinks
+  module UrlHelper
+    class << self
+      def magic_link_for(user, template_name, path, expiry = nil)
+        template = MagicLinks::Templates.find(template_name)
+        raise ArgumentError, 'Template not found' unless template.present?
+
+        template.magic_link_for(user, path, expiry)
+      end
+
+      def magic_url_for(user, template_name, path, expiry = nil)
+        template = MagicLinks::Templates.find(template_name)
+        raise ArgumentError, 'Template not found' unless template.present?
+
+        template.magic_url_for(user, path, expiry)
+      end
+    end
+
+    def magic_link_for(user, template_name, path, expiry = nil)
+      MagicLinks::UrlHelper.magic_link_for(user, template_name, path, expiry)
+    end
+
+    def magic_url_for(user, template_name, path, expiry = nil)
+      MagicLinks::UrlHelper.magic_url_for(user, template_name, path, expiry)
+    end
+  end
+end

data/app/models/magic_links/application_record.rb

@@ -0,0 +1,5 @@
+module MagicLinks
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/magic_links/magic_token.rb

@@ -0,0 +1,110 @@
+module MagicLinks
+  class MagicToken < ApplicationRecord
+    belongs_to :magic_token_authenticatable, polymorphic: true
+
+    validates :token, presence: true
+    validates :target_path, presence: true
+    validates :action_scope, presence: true
+    validate :token_expiry
+
+    after_initialize :ensure_token
+    before_create :ensure_unique_token
+
+    TOKEN_STRENGTHS = {
+      mild: 8,
+      moderate: 16,
+      strong: 32,
+    }.with_indifferent_access.freeze
+
+    class << self
+      TOKEN_STRENGTHS.each_key do |strength|
+        define_method(strength) do |authenticatable, target_path, action_scope|
+          MagicToken.new(target_path: target_path, action_scope: action_scope).tap do |token|
+            token.magic_token_authenticatable = authenticatable
+            token.send(:strength=, strength)
+            token.save!
+          end
+        end
+      end
+
+      def for(authenticatable:, target_path:, action_scope:, strength:, expiry: nil)
+        send(strength, authenticatable, target_path, action_scope).tap do |token|
+          token.expire_in(expiry) if expiry.present?
+        end
+      end
+    end
+
+    def expired?
+      expires_at&.past?
+    end
+
+    def expire_in(duration)
+      update_attribute :expires_at, (Time.zone.now + duration)
+      self
+    end
+
+    def mild?
+      strength == :mild
+    end
+
+    def moderate?
+      strength == :moderate
+    end
+
+    def strong?
+      strength == :strong
+    end
+
+    def scope
+      return unless magic_token_authenticatable.present?
+
+      magic_token_authenticatable.model_name.singular.to_sym
+    end
+
+    private
+
+    def token_expiry
+      return unless expired?
+
+      errors.add(:base, 'Token has expired')
+    end
+
+    def strength=(val)
+      self.token = generate_token(val)
+    end
+
+    def strength
+      token_strength || :moderate
+    end
+
+    def token_strength
+      return unless token
+
+      case token.length
+      when 32..64
+        :strong
+      when 16..31
+        :moderate
+      else
+        :mild
+      end
+    end
+
+    def ensure_token
+      self.token ||= generate_token(strength)
+    end
+
+    def generate_token(strength)
+      Devise.friendly_token(TOKEN_STRENGTHS[strength])
+    end
+
+    def ensure_unique_token
+      self.token ||= generate_token(strength)
+      loop do
+        return unless MagicToken.where(token: token).first
+
+        self.token = generate_token(strength)
+      end
+    end
+  end
+end

data/db/migrate/20211215150823_create_magic_links_magic_tokens.rb

@@ -0,0 +1,15 @@
+class CreateMagicLinksMagicTokens < ActiveRecord::Migration[5.2]
+  def change
+    create_table :magic_links_magic_tokens do |t|
+      t.string :token, null: false
+      t.string :target_path, null: false
+      t.json :action_scope, null: false
+      t.datetime :expires_at
+      t.references :magic_token_authenticatable, polymorphic: true, index: {name: 'index_magic_tokens_on_magic_token_authenticatable'}
+
+      t.timestamps
+    end
+
+    add_index :magic_links_magic_tokens, :token, unique: true
+  end
+end

data/lib/magic_links/engine.rb

@@ -0,0 +1,13 @@
+require 'devise'
+
+module MagicLinks
+  class Engine < ::Rails::Engine
+    isolate_namespace MagicLinks
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+  end
+end

data/lib/magic_links/middleware/magic_token_redirect.rb

@@ -0,0 +1,78 @@
+module MagicLinks
+  module Middleware
+    class MagicTokenRedirect
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Handler.new(env).handle || app.call(env)
+      end
+
+      private
+
+      attr_reader :app
+
+      class Handler
+        def initialize(env)
+          @request = ActionDispatch::Request.new(env)
+        end
+
+        def handle
+          return unless redirect_request?
+          return root unless magic_token.present?
+
+          cookies.signed[magic_token_key] = magic_token.token if scope
+          respond_with_redirect magic_token.target_path
+        end
+
+        def root
+          respond_with_redirect '/', 'to the home page (token not found)'
+        end
+
+        attr_reader :request
+
+        def path
+          request.path
+        end
+
+        def redirect_request?
+          Templates.match?(path)
+        end
+
+        def magic_token
+          return unless token
+
+          @magic_token ||= MagicToken.find_by(token: token)
+        end
+
+        def token
+          @token ||= Templates.token_for(path)
+        end
+
+        def scope
+          magic_token&.scope
+        end
+
+        private
+
+        def respond_with(status, headers, body)
+          ActionDispatch::Response.new(status, headers, body).to_a
+        end
+
+        def respond_with_redirect(path, path_desc = '')
+          body = %(You are being redirected <a href="#{path}">#{path_desc.present? ? path_desc : path}</a>)
+          ActionDispatch::Response.new(302, {'Location' => path}, body).to_a
+        end
+
+        def magic_token_key
+          "#{scope}_magic_token"
+        end
+
+        def cookies
+          request.cookie_jar
+        end
+      end
+    end
+  end
+end

data/lib/magic_links/rails.rb

@@ -0,0 +1,23 @@
+module MagicLinks
+  class Engine < ::Rails::Engine
+
+    initializer 'magic_links.url_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include MagicLinks::UrlHelper
+      end
+    end
+
+    initializer 'magic_links.middleware_redirect', before: :build_middleware_stack do |app|
+      app.config.middleware.insert_after ActionDispatch::Cookies, MagicLinks::Middleware::MagicTokenRedirect
+    end
+
+    initializer 'magic_links.devise_strategy' do
+      Warden::Strategies.add(:magic_token_authentication, MagicLinks::Strategies::MagicTokenAuthentication)
+      Devise.setup do |config|
+        config.warden do |manager|
+          manager.default_strategies(scope: :user).unshift :magic_token_authentication
+        end
+      end
+    end
+  end
+end

data/lib/magic_links/strategies/magic_token_authentication.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+module MagicLinks
+  module Strategies
+    class MagicTokenAuthentication < Devise::Strategies::Base
+      def valid?
+        magic_token_cookie.present?
+      end
+
+      def authenticate!
+        return unless magic_token.present? && magic_token.valid?
+        return unless valid_devise_mapping?
+        return unless permitted_action?
+
+        success!(resource)
+      end
+
+      def store?
+        false
+      end
+
+      def clean_up_csrf?
+        false
+      end
+
+      private
+
+      def valid_devise_mapping?
+        mapping.to == resource.class
+      end
+
+      def permitted_action?
+        return false unless permitted_controller?
+
+        Array(action_scope[controller]).include? action
+      end
+
+      def permitted_controller?
+        action_scope.keys.include? controller
+      end
+
+      def action_scope
+        magic_token.action_scope.with_indifferent_access
+      end
+
+      def resource
+        magic_token.magic_token_authenticatable
+      end
+
+      def magic_token
+        @magic_token ||= MagicToken.find_by token: magic_token_cookie
+      end
+
+      def magic_token_key
+        "#{scope}_magic_token"
+      end
+
+      def magic_token_cookie
+        @magic_token_cookie ||= cookies.signed[magic_token_key]
+      end
+
+      def controller
+        params[:controller]
+      end
+
+      def action
+        params[:action]
+      end
+    end
+  end
+end

data/lib/magic_links/template.rb

@@ -0,0 +1,67 @@
+module MagicLinks
+  class Template
+    VALID_TEMPLATE_PATTERN = %r{^/([A-Za-z0-9_\-]+)/(:token)$}.freeze
+
+    attr_reader :name, :pattern, :action_scope, :strength, :expiry
+
+    def initialize(pattern:, action_scope:, strength:, expiry:)
+      raise ArgumentError, "Pattern must be of the form '/xyz/:token'" unless VALID_TEMPLATE_PATTERN.match?(pattern)
+
+      @pattern = pattern
+      @action_scope = action_scope
+      @strength = strength
+      @expiry = expiry
+    end
+
+    def match?(path)
+      matcher.match?(path)
+    end
+
+    def token_for(path)
+      matcher.match(path)&.captures&.first
+    end
+
+    def magic_link_for(user, path, expiry = nil)
+      expiry ||= self.expiry
+      magic_token = magic_token_for(user, path, expiry)
+      pattern.sub(':token', magic_token.token)
+    end
+
+    def magic_url_for(user, path, expiry = nil)
+      url_for(magic_link_for(user, path, expiry))
+    end
+
+    private
+
+    def url_for(path)
+      ActionDispatch::Http::URL.url_for(default_url_options.merge(path: path))
+    end
+
+    def default_url_options
+      Rails.application.routes.default_url_options
+    end
+
+    def magic_token_for(user, path, expiry)
+      MagicToken.for(magic_token_params_for(user, path, expiry))
+    end
+
+    def magic_token_params_for(user, path, expiry)
+      {
+        authenticatable: user,
+        target_path: path,
+        action_scope: action_scope,
+        strength: strength,
+        expiry: expiry
+      }
+    end
+
+    def matcher
+      @matcher ||= build_matcher
+    end
+
+    def build_matcher
+      sections = VALID_TEMPLATE_PATTERN.match(pattern).captures
+      %r{^/#{sections[0]}/([A-Za-z0-9_\-]+)$}
+    end
+  end
+end

data/lib/magic_links/templates.rb

@@ -0,0 +1,32 @@
+module MagicLinks
+  module Templates
+    class << self
+      def add(name:, pattern:, action_scope:, strength:, expiry: nil)
+        templates[name] = Template.new(pattern: pattern,
+                                       action_scope: action_scope,
+                                       strength: strength,
+                                       expiry: expiry)
+      end
+
+      def find(name)
+        templates[name]
+      end
+
+      def match?(path)
+        templates.values.any? do |template|
+          template.match? path
+        end
+      end
+
+      def token_for(path)
+        templates.values.find { |template| template.match?(path) }&.token_for(path)
+      end
+
+      private
+
+      def templates
+        @templates ||= {}
+      end
+    end
+  end
+end

data/lib/magic_links/version.rb

@@ -0,0 +1,7 @@
+module MagicLinks
+  VERSION = '1.0.1'
+
+  def self.version
+    VERSION
+  end
+end

data/lib/magic_links.rb

@@ -0,0 +1,12 @@
+require 'magic_links/engine'
+require 'magic_links/template'
+require 'magic_links/templates'
+require 'magic_links/middleware/magic_token_redirect'
+require 'magic_links/strategies/magic_token_authentication'
+require 'magic_links/rails'
+
+module MagicLinks
+  def self.add_template(*args)
+    MagicLinks::Templates.add(*args)
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: magic_links
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- James wozniak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: devise
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Manages the creation and use of 'magic' tokens. These can be used to
+  provide authenticated access to a subset of controller actions, avoiding the need
+  for users to be signed in.
+email:
+- wozza35@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/helpers/magic_links/url_helper.rb
+- app/models/magic_links/application_record.rb
+- app/models/magic_links/magic_token.rb
+- db/migrate/20211215150823_create_magic_links_magic_tokens.rb
+- lib/magic_links.rb
+- lib/magic_links/engine.rb
+- lib/magic_links/middleware/magic_token_redirect.rb
+- lib/magic_links/rails.rb
+- lib/magic_links/strategies/magic_token_authentication.rb
+- lib/magic_links/template.rb
+- lib/magic_links/templates.rb
+- lib/magic_links/version.rb
+homepage: https://github.com/ClickMechanic/magic_links
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/ClickMechanic/magic_links
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Token based authentication
+test_files: []