dlnk_auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0d19743950394185b34f027606b621b9ed289ec80d37ff3086ad761c8869f3c
+  data.tar.gz: d3913fffd2763cc6aa0b79ce9a324d3433214a14541503317c99eb01052002ad
+SHA512:
+  metadata.gz: 11bdc33693539a8b731ee7d1969178003e0ca63caf6cf04e6c837e1ff50a6b68e56bbf9fe6cd2c89f255ab605dd4439ab073975a6845a4209da567a5f3802a1c
+  data.tar.gz: 7659d49342261e67ca7074dfbbc19fc5344fe3f24874c0a86bcbcd36bf42517c91c2da3368e08aabefe0a457538dfac70dd0af663198ec78bde0686c58b706bc

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DALiNK
+
+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,197 @@
+# DlnkAuth
+
+Passwordless magic link authentication engine for Rails.
+
+DlnkAuth provides a complete sign-in flow using one-time codes and magic links, with opt-in modules for impersonation and multi-tenancy. It is designed as a Rails Engine that mounts into your application.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "dlnk_auth"
+```
+
+Run the install generator:
+
+```bash
+bundle install
+rails generate dlnk_auth:install
+rails db:migrate
+```
+
+The generator will:
+
+1. Copy an initializer to `config/initializers/dlnk_auth.rb`
+2. Copy migrations for sessions and magic links
+3. Add the engine route to `config/routes.rb`
+
+## Setup
+
+### User model
+
+Include the `Authenticatable` concern in your User model:
+
+```ruby
+class User < ApplicationRecord
+  include DlnkAuth::Authenticatable
+end
+```
+
+This adds:
+
+- `has_many :dlnk_auth_sessions` and `has_many :dlnk_auth_magic_links`
+- Email normalization (strip + downcase)
+- Email presence and format validation
+- `#send_magic_link` instance method
+
+### Application controller
+
+Include the `Authentication` concern in your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include DlnkAuth::Authentication
+end
+```
+
+This provides:
+
+- `before_action :require_authentication` (applied by default)
+- `authenticated?` and `current_user` helper methods
+- `allow_unauthenticated_access` and `require_unauthenticated_access` class methods
+- Session management via signed cookies
+
+For controllers that should be accessible without sign-in:
+
+```ruby
+class PublicController < ApplicationController
+  allow_unauthenticated_access
+end
+```
+
+## Configuration
+
+Edit `config/initializers/dlnk_auth.rb`:
+
+```ruby
+DlnkAuth.configure do |c|
+  # The user model class name
+  c.user_class = "User"
+
+  # Attribute used for email lookup
+  c.email_attribute = :email
+
+  # Length of one-time codes (Base32 Crockford)
+  c.code_length = 6
+
+  # How long magic links remain valid
+  c.magic_link_ttl = 15.minutes
+
+  # How long sessions last
+  c.session_ttl = 2.weeks
+
+  # Redirect paths after sign in / sign out
+  c.after_sign_in_path  = :root_path
+  c.after_sign_out_path = :root_path
+
+  # From address for magic link emails
+  c.mailer_sender = "noreply@example.com"
+
+  # Rate limiting for session creation attempts
+  c.rate_limit_sessions = { to: 10, within: 3.minutes }
+
+  # Rate limiting for code verification attempts
+  c.rate_limit_codes = { to: 10, within: 15.minutes }
+end
+```
+
+## Routes
+
+The engine mounts at `/auth` by default and provides:
+
+| Method   | Path              | Description                    |
+|----------|-------------------|--------------------------------|
+| `GET`    | `/auth/session/new` | Sign-in form (enter email)   |
+| `POST`   | `/auth/session`    | Create session (submit email) |
+| `DELETE` | `/auth/session`    | Sign out                      |
+| `GET`    | `/auth/magic_link` | Verify magic link token       |
+| `POST`   | `/auth/magic_link` | Verify one-time code          |
+
+## Impersonation (opt-in)
+
+Enable impersonation in the initializer:
+
+```ruby
+DlnkAuth.configure do |c|
+  c.impersonation.enabled = true
+end
+```
+
+When enabled, the `DlnkAuth::Impersonation` concern is automatically included in `ActionController::Base`. It provides:
+
+- `impersonate_user(user)` -- start impersonating
+- `stop_impersonating` -- return to your real account
+- `true_user` -- the originally signed-in user
+- `impersonating?` -- whether impersonation is active
+
+The engine exposes two impersonation routes:
+
+| Method   | Path                          | Description          |
+|----------|-------------------------------|----------------------|
+| `POST`   | `/auth/impersonation/:user_id` | Start impersonating |
+| `DELETE` | `/auth/impersonation`          | Stop impersonating  |
+
+The impersonation controller requires the current user to respond to `superadmin?` returning `true`. Add this method to your User model:
+
+```ruby
+class User < ApplicationRecord
+  include DlnkAuth::Authenticatable
+
+  def superadmin?
+    # your logic here
+    role == "superadmin"
+  end
+end
+```
+
+## Multi-tenancy (opt-in)
+
+Enable multi-tenancy in the initializer:
+
+```ruby
+DlnkAuth.configure do |c|
+  c.tenanting.enabled = true
+  c.tenanting.tenant_class = "Tenant"
+  c.tenanting.slug_attribute = :slug
+  c.tenanting.skip_paths = %w[/auth /assets /rails /up /cable]
+end
+```
+
+When enabled, the `DlnkAuth::Middleware::TenantResolver` Rack middleware is inserted automatically. It resolves the tenant from the first URL segment (e.g., `/acme/dashboard` resolves tenant with slug `acme`) and sets `DlnkAuth::Current.tenant`.
+
+Paths listed in `skip_paths` bypass tenant resolution.
+
+You can also provide a custom resolver:
+
+```ruby
+c.tenanting.tenant_resolver = ->(request) {
+  if request.path_info =~ %r{\A/([^/]+)}
+    Tenant.find_by(subdomain: $1)
+  end
+}
+```
+
+## View Customization
+
+Copy the engine views into your application for customization:
+
+```bash
+rails generate dlnk_auth:views
+```
+
+This copies all views to `app/views/dlnk_auth/` where you can modify them freely.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/concerns/dlnk_auth/authentication/via_magic_link.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Authentication
+    module ViaMagicLink
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :email_address_pending_authentication
+        after_action :ensure_development_magic_link_not_leaked
+      end
+
+      private
+        def ensure_development_magic_link_not_leaked
+          unless Rails.env.development? || Rails.env.test?
+            raise "Leaking magic link via flash in #{Rails.env}?" if flash[:magic_link_code].present?
+          end
+        end
+
+        def redirect_to_magic_link_verification(magic_link)
+          serve_development_magic_link(magic_link)
+          set_pending_authentication_token(magic_link)
+          redirect_to dlnk_auth.magic_link_path, notice: I18n.t("dlnk_auth.magic_links.code_sent")
+        end
+
+        def redirect_to_fake_magic_link_verification(email)
+          fake = DlnkAuth::MagicLink.new(
+            user: user_class.new(DlnkAuth.configuration.email_attribute => email),
+            code: DlnkAuth::Code.generate(DlnkAuth.configuration.code_length),
+            expires_at: DlnkAuth.configuration.magic_link_ttl.from_now
+          )
+          redirect_to_magic_link_verification(fake)
+        end
+
+        def serve_development_magic_link(magic_link)
+          if Rails.env.development? && magic_link.present?
+            flash[:magic_link_code] = magic_link.code
+          end
+        end
+
+        def set_pending_authentication_token(magic_link)
+          email = magic_link.user.public_send(DlnkAuth.configuration.email_attribute)
+          cookies[:pending_authentication_token] = {
+            value: pending_authentication_token_verifier.generate(email, expires_at: magic_link.expires_at),
+            httponly: true, same_site: :lax, expires: magic_link.expires_at
+          }
+        end
+
+        def email_address_pending_authentication
+          return @_email_pending_auth if defined?(@_email_pending_auth)
+          @_email_pending_auth = pending_authentication_token_verifier.verified(pending_authentication_token)
+        end
+
+        def pending_authentication_token_verifier
+          Rails.application.message_verifier(:pending_authentication)
+        end
+
+        def pending_authentication_token
+          cookies[:pending_authentication_token]
+        end
+
+        def clear_pending_authentication_token
+          cookies.delete(:pending_authentication_token)
+        end
+    end
+  end
+end

data/app/controllers/concerns/dlnk_auth/authentication.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :require_authentication
+      helper_method :authenticated?, :current_user, :current_tenant
+      include DlnkAuth::Authentication::ViaMagicLink
+    end
+
+    class_methods do
+      def require_unauthenticated_access(**options)
+        allow_unauthenticated_access(**options)
+        before_action :redirect_authenticated_user, **options
+      end
+
+      def allow_unauthenticated_access(**options)
+        skip_before_action :require_authentication, **options
+        before_action :resume_session, **options
+      end
+    end
+
+    private
+      def authenticated?
+        DlnkAuth::Current.session.present?
+      end
+
+      def current_user
+        DlnkAuth::Current.user
+      end
+
+      def current_tenant
+        DlnkAuth::Current.tenant
+      end
+
+      def require_authentication
+        resume_session || request_authentication
+      end
+
+      def resume_session
+        if (session_record = find_session_by_cookie)
+          set_current_session(session_record)
+        end
+      end
+
+      def find_session_by_cookie
+        DlnkAuth::Session.find_signed(cookies[:session_token])
+      end
+
+      def request_authentication
+        session[:return_to_after_authenticating] = request.fullpath
+        redirect_to dlnk_auth.new_session_path
+      end
+
+      def after_authentication_url
+        url = session.delete(:return_to_after_authenticating)
+        if url.present? && url.start_with?("/") && !url.start_with?("//")
+          url
+        else
+          main_app.send(DlnkAuth.configuration.after_sign_in_path)
+        end
+      end
+
+      def redirect_authenticated_user
+        redirect_to after_authentication_url if authenticated?
+      end
+
+      def start_new_session_for(user)
+        user.dlnk_auth_sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session_record|
+          set_current_session(session_record)
+        end
+      end
+
+      def set_current_session(session_record)
+        DlnkAuth::Current.session = session_record
+        DlnkAuth::Current.user = session_record.user
+        ttl = DlnkAuth.configuration.session_ttl
+        cookies[:session_token] = { value: session_record.signed_id(expires_in: ttl), httponly: true, same_site: :lax, expires: ttl&.from_now }
+      end
+
+      def terminate_session
+        DlnkAuth::Current.session&.destroy
+        cookies.delete(:session_token)
+      end
+
+      def user_class
+        DlnkAuth.configuration.user_class.constantize
+      end
+  end
+end

data/app/controllers/concerns/dlnk_auth/impersonation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Impersonation
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :true_user, :impersonating?
+    end
+
+    private
+      def impersonate_user(user)
+        session[:dlnk_auth_impersonated_user_id] = user.id
+        DlnkAuth::Current.user = user
+      end
+
+      def stop_impersonating
+        session.delete(:dlnk_auth_impersonated_user_id)
+        DlnkAuth::Current.user = true_user
+      end
+
+      def true_user
+        if session[:dlnk_auth_impersonated_user_id].present?
+          @_true_user ||= DlnkAuth::Current.session&.user
+        else
+          current_user
+        end
+      end
+
+      def impersonating?
+        session[:dlnk_auth_impersonated_user_id].present? && true_user != current_user
+      end
+
+      def current_user
+        if session[:dlnk_auth_impersonated_user_id].present?
+          @_impersonated_user ||= user_class.find_by(id: session[:dlnk_auth_impersonated_user_id])
+        else
+          DlnkAuth::Current.user
+        end
+      end
+
+      def require_superadmin
+        authorizer = DlnkAuth.configuration.impersonation.authorize_with
+        head :forbidden unless true_user && authorizer.call(true_user)
+      end
+  end
+end

data/app/controllers/dlnk_auth/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class ApplicationController < ActionController::Base
+    include DlnkAuth::Authentication
+  end
+end

data/app/controllers/dlnk_auth/impersonations_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class ImpersonationsController < ApplicationController
+    include DlnkAuth::Impersonation
+    before_action :require_impersonation_enabled
+    before_action :require_superadmin, only: :create
+
+    def create
+      user = user_class.find(params[:user_id])
+      impersonate_user(user)
+      redirect_back fallback_location: main_app.root_path
+    end
+
+    def destroy
+      stop_impersonating
+      redirect_back fallback_location: main_app.root_path
+    end
+
+    private
+      def require_impersonation_enabled
+        head :not_found unless DlnkAuth.configuration.impersonation.enabled
+      end
+  end
+end

data/app/controllers/dlnk_auth/magic_links_controller.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class MagicLinksController < ApplicationController
+    require_unauthenticated_access
+
+    # Rate limit per IP (default) — prevents single-source brute force
+    rate_limit to: DlnkAuth.configuration.rate_limit_codes[:to],
+               within: DlnkAuth.configuration.rate_limit_codes[:within],
+               only: :create,
+               name: "code-verification-per-ip",
+               with: :rate_limit_exceeded
+
+    # Rate limit per email — prevents distributed brute force across multiple IPs
+    rate_limit to: DlnkAuth.configuration.rate_limit_codes[:to],
+               within: DlnkAuth.configuration.rate_limit_codes[:within],
+               by: -> { email_address_pending_authentication || request.remote_ip },
+               only: :create,
+               name: "code-verification-per-email",
+               with: :rate_limit_exceeded
+
+    before_action :ensure_pending_authentication
+
+    def show
+    end
+
+    def create
+      pending_email = email_address_pending_authentication
+      if pending_email.present? && (magic_link = DlnkAuth::MagicLink.consume(code, email: pending_email))
+        authenticate(magic_link)
+      else
+        redirect_to magic_link_path, alert: I18n.t("dlnk_auth.magic_links.invalid_code")
+      end
+    end
+
+    private
+      def ensure_pending_authentication
+        unless email_address_pending_authentication.present?
+          redirect_to new_session_path, alert: I18n.t("dlnk_auth.magic_links.email_first")
+        end
+      end
+
+      def code
+        params[:code]
+      end
+
+      def authenticate(magic_link)
+        email_attr = DlnkAuth.configuration.email_attribute
+        if ActiveSupport::SecurityUtils.secure_compare(email_address_pending_authentication || "", magic_link.user.public_send(email_attr))
+          clear_pending_authentication_token
+          start_new_session_for(magic_link.user)
+          redirect_to after_authentication_url, notice: I18n.t("dlnk_auth.magic_links.signed_in")
+        else
+          clear_pending_authentication_token
+          redirect_to new_session_path, alert: I18n.t("dlnk_auth.magic_links.email_mismatch")
+        end
+      end
+
+      def rate_limit_exceeded
+        redirect_to magic_link_path, alert: I18n.t("dlnk_auth.magic_links.rate_limited")
+      end
+  end
+end

data/app/controllers/dlnk_auth/sessions_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class SessionsController < ApplicationController
+    require_unauthenticated_access except: :destroy
+    rate_limit to: DlnkAuth.configuration.rate_limit_sessions[:to],
+               within: DlnkAuth.configuration.rate_limit_sessions[:within],
+               only: :create,
+               with: :rate_limit_exceeded
+
+    def new
+    end
+
+    def create
+      if (user = user_class.find_by(email_attribute => email_address))
+        magic_link = user.send_magic_link
+        redirect_to_magic_link_verification(magic_link)
+      else
+        redirect_to_fake_magic_link_verification(email_address)
+      end
+    end
+
+    def destroy
+      terminate_session
+      redirect_to main_app.send(DlnkAuth.configuration.after_sign_out_path), notice: I18n.t("dlnk_auth.sessions.signed_out")
+    end
+
+    private
+      def email_address
+        params[:email_address]
+      end
+
+      def email_attribute
+        DlnkAuth.configuration.email_attribute
+      end
+
+      def rate_limit_exceeded
+        redirect_to new_session_path, alert: I18n.t("dlnk_auth.sessions.rate_limited")
+      end
+  end
+end

data/app/mailers/dlnk_auth/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class ApplicationMailer < ActionMailer::Base
+    default from: -> { DlnkAuth.configuration.mailer_sender }
+    layout "mailer"
+  end
+end

data/app/mailers/dlnk_auth/magic_link_mailer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class MagicLinkMailer < ApplicationMailer
+    def sign_in_instructions(user, email, code)
+      @user = user
+      @code = code
+
+      mail(
+        to: email,
+        subject: I18n.t("dlnk_auth.mailer.sign_in_instructions.subject")
+      )
+    end
+  end
+end

data/app/models/concerns/dlnk_auth/authenticatable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Authenticatable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :dlnk_auth_sessions, class_name: "DlnkAuth::Session", as: :user, dependent: :destroy
+      has_many :dlnk_auth_magic_links, class_name: "DlnkAuth::MagicLink", as: :user, dependent: :destroy
+
+      normalizes DlnkAuth.configuration.email_attribute, with: ->(email) { email.strip.downcase }
+
+      validates DlnkAuth.configuration.email_attribute,
+        presence: true,
+        format: { with: URI::MailTo::EMAIL_REGEXP }
+    end
+
+    def send_magic_link
+      email_value = public_send(DlnkAuth.configuration.email_attribute)
+      magic_link = dlnk_auth_magic_links.create!(email: email_value)
+      DlnkAuth::MagicLinkMailer.sign_in_instructions(self, email_value, magic_link.code).deliver_later
+      magic_link
+    end
+  end
+end

data/app/models/dlnk_auth/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/dlnk_auth/current.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :session, :user, :tenant
+  end
+end

data/app/models/dlnk_auth/magic_link.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module DlnkAuth
+  class MagicLink < ApplicationRecord
+    attr_accessor :code
+
+    belongs_to :user, polymorphic: true
+
+    scope :active, -> { where(expires_at: Time.current...) }
+    scope :stale, -> { where(expires_at: ..Time.current) }
+
+    before_validation :generate_code_digest, on: :create
+    before_validation :set_expiration, on: :create
+
+    validates :code_digest, uniqueness: true, presence: true
+    validates :email, presence: true
+
+    class << self
+      def consume(code, email:)
+        sanitized = DlnkAuth::Code.sanitize(code)
+        return nil unless sanitized.present?
+
+        digest = Digest::SHA256.hexdigest(sanitized)
+        transaction do
+          active.where(email: email).lock.includes(:user).find_by(code_digest: digest)&.consume
+        end
+      end
+
+      def cleanup
+        stale.delete_all
+      end
+    end
+
+    def consume
+      destroy
+      self
+    end
+
+    private
+      def generate_code_digest
+        self.code ||= loop do
+          candidate = DlnkAuth::Code.generate(DlnkAuth.configuration.code_length)
+          digest = Digest::SHA256.hexdigest(candidate)
+          break candidate unless self.class.exists?(code_digest: digest)
+        end
+        self.code_digest = Digest::SHA256.hexdigest(self.code)
+      end
+
+      def set_expiration
+        self.expires_at ||= DlnkAuth.configuration.magic_link_ttl.from_now
+      end
+  end
+end

data/app/models/dlnk_auth/session.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class Session < ApplicationRecord
+    belongs_to :user, polymorphic: true
+
+    scope :stale, -> {
+      ttl = DlnkAuth.configuration.session_ttl
+      ttl ? where(created_at: ..ttl.ago) : none
+    }
+
+    def self.cleanup
+      stale.delete_all
+    end
+  end
+end

data/app/views/dlnk_auth/magic_link_mailer/sign_in_instructions.html.erb

@@ -0,0 +1,7 @@
+<h2>Your sign in code</h2>
+<p>Your code is:</p>
+<p style="font-size: 32px; font-weight: bold; letter-spacing: 8px; text-align: center; padding: 16px; background: #f3f4f6; border-radius: 8px; font-family: monospace;">
+  <%= @code %>
+</p>
+<p>This code expires in <%= distance_of_time_in_words(DlnkAuth.configuration.magic_link_ttl) %>.</p>
+<p>If you didn't request this, please ignore this email.</p>

data/app/views/dlnk_auth/magic_link_mailer/sign_in_instructions.text.erb

@@ -0,0 +1,7 @@
+Your sign in code
+
+Your code is: <%= @code %>
+
+This code expires in <%= distance_of_time_in_words(DlnkAuth.configuration.magic_link_ttl) %>.
+
+If you didn't request this, please ignore this email.

data/app/views/dlnk_auth/magic_links/show.html.erb

@@ -0,0 +1,20 @@
+<div style="max-width: 400px; margin: 100px auto; padding: 20px;">
+  <h1>Enter your code</h1>
+  <p>We sent a code to <strong><%= email_address_pending_authentication %></strong></p>
+  <% if flash[:magic_link_code] %>
+    <div style="margin: 16px 0; padding: 12px; background: #f0f0f0; border-radius: 8px; text-align: center;">
+      <small>Dev code:</small><br>
+      <strong style="font-size: 24px; letter-spacing: 8px; font-family: monospace;"><%= flash[:magic_link_code] %></strong>
+    </div>
+  <% end %>
+  <%= form_with url: dlnk_auth.magic_link_path, method: :post do |f| %>
+    <div style="margin-bottom: 16px;">
+      <%= f.label :code, "Code" %><br>
+      <%= f.text_field :code, required: true, autofocus: true, autocomplete: "one-time-code", maxlength: DlnkAuth.configuration.code_length, style: "width: 100%; padding: 8px; text-align: center; font-size: 20px; letter-spacing: 8px; font-family: monospace; text-transform: uppercase;" %>
+    </div>
+    <%= f.submit "Verify", style: "width: 100%; padding: 10px; cursor: pointer;" %>
+  <% end %>
+  <p style="margin-top: 16px; text-align: center;">
+    <%= link_to "Back to email", dlnk_auth.new_session_path %>
+  </p>
+</div>

data/app/views/dlnk_auth/sessions/new.html.erb

@@ -0,0 +1,10 @@
+<div style="max-width: 400px; margin: 100px auto; padding: 20px;">
+  <h1>Sign in</h1>
+  <%= form_with url: dlnk_auth.session_path, method: :post do |f| %>
+    <div style="margin-bottom: 16px;">
+      <%= f.label :email_address, "Email address" %><br>
+      <%= f.email_field :email_address, required: true, autofocus: true, autocomplete: "email", style: "width: 100%; padding: 8px;" %>
+    </div>
+    <%= f.submit "Send sign in code", style: "width: 100%; padding: 10px; cursor: pointer;" %>
+  <% end %>
+</div>

data/app/views/layouts/dlnk_auth/application.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Sign in</title>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+  <% if flash[:alert] %>
+    <div style="max-width: 400px; margin: 16px auto; padding: 12px; background: #fee; border: 1px solid #fcc; border-radius: 4px; color: #c00;">
+      <%= flash[:alert] %>
+    </div>
+  <% end %>
+  <% if flash[:notice] %>
+    <div style="max-width: 400px; margin: 16px auto; padding: 12px; background: #efe; border: 1px solid #cfc; border-radius: 4px; color: #0a0;">
+      <%= flash[:notice] %>
+    </div>
+  <% end %>
+  <%= yield %>
+</body>
+</html>

data/app/views/layouts/mailer.html.erb

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <style>
+    /* Email styles */
+  </style>
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,15 @@
+en:
+  dlnk_auth:
+    sessions:
+      rate_limited: "Too many requests. Try again later."
+      signed_out: "You have been signed out."
+    magic_links:
+      rate_limited: "Too many attempts. Try again later."
+      invalid_code: "Invalid or expired code. Please try again."
+      email_first: "Please enter your email first."
+      email_mismatch: "Email mismatch. Please try again."
+      signed_in: "Signed in successfully."
+      code_sent: "If this email address is registered, you will receive a sign-in code shortly."
+    mailer:
+      sign_in_instructions:
+        subject: "Your sign in code"

data/config/routes.rb

@@ -0,0 +1,7 @@
+DlnkAuth::Engine.routes.draw do
+  resource :session, only: [ :new, :create, :destroy ]
+  resource :magic_link, only: [ :show, :create ]
+
+  post "impersonation/:user_id", to: "impersonations#create", as: :impersonation
+  delete "impersonation", to: "impersonations#destroy"
+end

data/db/migrate/20260215000001_create_dlnk_auth_sessions.rb

@@ -0,0 +1,10 @@
+class CreateDlnkAuthSessions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :dlnk_auth_sessions do |t|
+      t.references :user, null: false, polymorphic: true
+      t.string :ip_address
+      t.string :user_agent
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260215000002_create_dlnk_auth_magic_links.rb

@@ -0,0 +1,13 @@
+class CreateDlnkAuthMagicLinks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :dlnk_auth_magic_links do |t|
+      t.references :user, null: false, polymorphic: true
+      t.string :email, null: false
+      t.string :code_digest, null: false
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+
+    add_index :dlnk_auth_magic_links, :code_digest, unique: true
+  end
+end

data/db/migrate/20260215000005_add_expires_at_index_to_dlnk_auth_magic_links.rb

@@ -0,0 +1,5 @@
+class AddExpiresAtIndexToDlnkAuthMagicLinks < ActiveRecord::Migration[8.0]
+  def change
+    add_index :dlnk_auth_magic_links, :expires_at
+  end
+end

data/lib/dlnk_auth/code.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module DlnkAuth
+  module Code
+    BASE32_ALPHABET = %w[0 1 2 3 4 5 6 7 8 9 A B C D E F G H J K M N P Q R S T V W X Y Z].freeze
+    SUBSTITUTIONS = { "O" => "0", "I" => "1", "L" => "1" }.freeze
+
+    class << self
+      def generate(length)
+        Array.new(length) { BASE32_ALPHABET[SecureRandom.random_number(BASE32_ALPHABET.size)] }.join
+      end
+
+      def sanitize(code)
+        if code.present?
+          code.to_s.upcase
+            .then { |c| SUBSTITUTIONS.reduce(c) { |result, (from, to)| result.gsub(from, to) } }
+            .then { |c| c.gsub(/[^#{BASE32_ALPHABET.join}]/, "") }
+        end
+      end
+    end
+  end
+end

data/lib/dlnk_auth/configuration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class Configuration
+    attr_accessor :user_class, :email_attribute, :code_length,
+                  :magic_link_ttl, :session_ttl,
+                  :after_sign_in_path, :after_sign_out_path,
+                  :mailer_sender,
+                  :rate_limit_sessions, :rate_limit_codes
+
+    attr_reader :impersonation, :tenanting
+
+    def initialize
+      @user_class        = "User"
+      @email_attribute   = :email
+      @code_length       = 6
+      @magic_link_ttl    = 15.minutes
+      @session_ttl       = 2.weeks
+      @after_sign_in_path  = :root_path
+      @after_sign_out_path = :root_path
+      @mailer_sender     = "noreply@example.com"
+      @rate_limit_sessions = { to: 10, within: 3.minutes }
+      @rate_limit_codes    = { to: 10, within: 15.minutes }
+      @impersonation = ImpersonationConfig.new
+      @tenanting     = TenantingConfig.new
+    end
+
+    def initialize_copy(original)
+      super
+      @impersonation = original.impersonation.dup
+      @tenanting = original.tenanting.dup
+    end
+
+    def validate!
+      raise ArgumentError, "user_class must be a String" unless user_class.is_a?(String)
+      raise ArgumentError, "code_length must be a positive Integer" unless code_length.is_a?(Integer) && code_length > 0
+      raise ArgumentError, "email_attribute must be a Symbol" unless email_attribute.is_a?(Symbol)
+      raise ArgumentError, "magic_link_ttl must respond to :from_now" unless magic_link_ttl.respond_to?(:from_now)
+      raise ArgumentError, "session_ttl must respond to :from_now or be nil" unless session_ttl.nil? || session_ttl.respond_to?(:from_now)
+      raise ArgumentError, "mailer_sender must be present" if mailer_sender.blank?
+      validate_rate_limit_hash!(:rate_limit_sessions, rate_limit_sessions)
+      validate_rate_limit_hash!(:rate_limit_codes, rate_limit_codes)
+      raise ArgumentError, "impersonation.authorize_with must respond to :call" unless impersonation.authorize_with.respond_to?(:call)
+    end
+
+    class ImpersonationConfig
+      attr_accessor :enabled, :authorize_with
+
+      def initialize
+        @enabled = false
+        @authorize_with = ->(user) { user.superadmin? }
+      end
+    end
+
+    class TenantingConfig
+      attr_accessor :enabled, :tenant_class, :slug_attribute,
+                    :skip_paths, :tenant_resolver
+
+      def initialize
+        @enabled        = false
+        @tenant_class   = "Tenant"
+        @slug_attribute = :slug
+        @skip_paths     = %w[/auth /assets /rails /up /cable]
+        @tenant_resolver = nil
+      end
+    end
+
+    private
+      def validate_rate_limit_hash!(name, value)
+        unless value.is_a?(Hash) && value.key?(:to) && value.key?(:within)
+          raise ArgumentError, "#{name} must be a Hash with :to and :within keys"
+        end
+      end
+  end
+end

data/lib/dlnk_auth/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  class Engine < ::Rails::Engine
+    isolate_namespace DlnkAuth
+
+    initializer "dlnk_auth.middleware" do |app|
+      if DlnkAuth.configuration.tenanting.enabled
+        app.middleware.insert_after Rack::TempfileReaper, DlnkAuth::Middleware::TenantResolver
+      end
+    end
+
+    initializer "dlnk_auth.configuration_validation", after: :load_config_initializers do
+      DlnkAuth.configuration.validate!
+    end
+
+    initializer "dlnk_auth.i18n" do
+      DlnkAuth::Engine.root.glob("config/locales/**/*.yml").each do |locale|
+        I18n.load_path << locale unless I18n.load_path.include?(locale)
+      end
+    end
+  end
+end

data/lib/dlnk_auth/middleware/tenant_resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Middleware
+    class TenantResolver
+      SLUG_PATTERN = %r{\A/([a-z0-9][a-z0-9\-]*[a-z0-9]|[a-z0-9])}
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        config = DlnkAuth.configuration.tenanting
+        return @app.call(env) unless config.enabled
+
+        request = ActionDispatch::Request.new(env)
+        path = request.path_info
+
+        return @app.call(env) if skip_path?(path, config)
+
+        tenant = resolve_tenant(request, config)
+
+        if tenant
+          rewrite_path(request, path)
+          DlnkAuth::Current.tenant = tenant
+        end
+
+        @app.call(env)
+      ensure
+        DlnkAuth::Current.reset if config&.enabled
+      end
+
+      private
+        def skip_path?(path, config)
+          return true if path == "/"
+          config.skip_paths.any? { |prefix| path.start_with?(prefix) }
+        end
+
+        def resolve_tenant(request, config)
+          if config.tenant_resolver
+            config.tenant_resolver.call(request)
+          else
+            resolve_by_slug(request.path_info, config)
+          end
+        end
+
+        def resolve_by_slug(path, config)
+          if (match = path.match(SLUG_PATTERN))
+            slug = match[1].downcase
+            tenant_class = config.tenant_class.constantize
+            tenant_class.find_by(config.slug_attribute => slug)
+          end
+        end
+
+        def rewrite_path(request, path)
+          if (match = path.match(SLUG_PATTERN))
+            matched = match[0]
+            request.env["SCRIPT_NAME"] = request.script_name + matched
+            remaining = path.delete_prefix(matched)
+            request.env["PATH_INFO"] = remaining.empty? ? "/" : remaining
+          end
+        end
+    end
+  end
+end

data/lib/dlnk_auth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  VERSION = "0.1.0"
+end

data/lib/dlnk_auth.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "dlnk_auth/version"
+require "dlnk_auth/configuration"
+require "dlnk_auth/code"
+require "dlnk_auth/middleware/tenant_resolver"
+require "dlnk_auth/engine"
+
+module DlnkAuth
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/generators/dlnk_auth/install/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/dlnk_auth.rb"
+      end
+
+      def copy_migrations
+        rails_command "dlnk_auth:install:migrations"
+      end
+
+      def add_route
+        route 'mount DlnkAuth::Engine => "/auth"'
+      end
+
+      def show_post_install
+        say ""
+        say "DlnkAuth installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Edit config/initializers/dlnk_auth.rb"
+        say "  2. Add `include DlnkAuth::Authenticatable` to your User model"
+        say "  3. Add `include DlnkAuth::Authentication` to your ApplicationController"
+        say "  4. Run `rails db:migrate`"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/dlnk_auth/install/templates/initializer.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+DlnkAuth.configure do |c|
+  # Core auth
+  c.user_class        = "User"
+  c.email_attribute   = :email
+  c.code_length       = 6
+  c.magic_link_ttl    = 15.minutes
+  c.session_ttl       = 2.weeks
+  c.after_sign_in_path  = :root_path
+  c.after_sign_out_path = :root_path
+  c.mailer_sender     = "noreply@example.com"
+
+  # Rate limiting
+  c.rate_limit_sessions = { to: 10, within: 3.minutes }
+  c.rate_limit_codes    = { to: 10, within: 15.minutes }
+
+  # Impersonation (opt-in)
+  # c.impersonation.enabled = true
+
+  # Multi-tenancy (opt-in)
+  # c.tenanting.enabled = true
+  # c.tenanting.tenant_class = "Tenant"
+  # c.tenanting.slug_attribute = :slug
+  # c.tenanting.skip_paths = %w[/auth /assets /rails /up /cable]
+end

data/lib/generators/dlnk_auth/views/views_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DlnkAuth
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root DlnkAuth::Engine.root.join("app/views/dlnk_auth")
+
+      def copy_views
+        directory ".", "app/views/dlnk_auth"
+      end
+
+      def show_info
+        say ""
+        say "DlnkAuth views copied to app/views/dlnk_auth/", :green
+        say "You can now customize the sign-in pages."
+        say ""
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: dlnk_auth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DALiNK
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: A Rails Engine providing passwordless magic link authentication with
+  opt-in impersonation and multi-tenancy modules.
+email:
+- contact@dalink.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/concerns/dlnk_auth/authentication.rb
+- app/controllers/concerns/dlnk_auth/authentication/via_magic_link.rb
+- app/controllers/concerns/dlnk_auth/impersonation.rb
+- app/controllers/dlnk_auth/application_controller.rb
+- app/controllers/dlnk_auth/impersonations_controller.rb
+- app/controllers/dlnk_auth/magic_links_controller.rb
+- app/controllers/dlnk_auth/sessions_controller.rb
+- app/mailers/dlnk_auth/application_mailer.rb
+- app/mailers/dlnk_auth/magic_link_mailer.rb
+- app/models/concerns/dlnk_auth/authenticatable.rb
+- app/models/dlnk_auth/application_record.rb
+- app/models/dlnk_auth/current.rb
+- app/models/dlnk_auth/magic_link.rb
+- app/models/dlnk_auth/session.rb
+- app/views/dlnk_auth/magic_link_mailer/sign_in_instructions.html.erb
+- app/views/dlnk_auth/magic_link_mailer/sign_in_instructions.text.erb
+- app/views/dlnk_auth/magic_links/show.html.erb
+- app/views/dlnk_auth/sessions/new.html.erb
+- app/views/layouts/dlnk_auth/application.html.erb
+- app/views/layouts/mailer.html.erb
+- config/locales/en.yml
+- config/routes.rb
+- db/migrate/20260215000001_create_dlnk_auth_sessions.rb
+- db/migrate/20260215000002_create_dlnk_auth_magic_links.rb
+- db/migrate/20260215000005_add_expires_at_index_to_dlnk_auth_magic_links.rb
+- lib/dlnk_auth.rb
+- lib/dlnk_auth/code.rb
+- lib/dlnk_auth/configuration.rb
+- lib/dlnk_auth/engine.rb
+- lib/dlnk_auth/middleware/tenant_resolver.rb
+- lib/dlnk_auth/version.rb
+- lib/generators/dlnk_auth/install/install_generator.rb
+- lib/generators/dlnk_auth/install/templates/initializer.rb.tt
+- lib/generators/dlnk_auth/views/views_generator.rb
+homepage: https://github.com/dalink/dlnk_auth
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.1
+specification_version: 4
+summary: Passwordless magic link authentication engine for Rails
+test_files: []