sqrl-rails 0.1.0

data/lib/sqrl/rails/stores/cache.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Store implementations shipped with the Rails integration.
+    module Stores
+      # The three {SQRL::Server} store interfaces on an +ActiveSupport::Cache::Store+, for
+      # applications that keep short-lived login state in Redis or Memcached rather than
+      # in the database:
+      #
+      #   config.sqrl.stores = :cache               # uses Rails.cache
+      #   config.sqrl.cache_store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"])
+      #
+      # Single use is implemented as read-then-+delete+: every supported store deletes a
+      # key atomically and reports whether it existed, so concurrent consumers of one nut
+      # or one CPS token see exactly one winner. Nuts and pending logins expire through
+      # the cache's own TTL, so +prune!+ has nothing to do.
+      #
+      # Identities are durable account data and are kept here too (they are what a
+      # cache store makes you lose on eviction), so this set is meant for sites whose
+      # cache is persistent (Redis with persistence) or that pair it with their own
+      # identity store:
+      #
+      #   stores = SQRL::Rails::Stores::Cache.stores(Rails.cache)
+      #   stores.identities = SQRL::Rails::Stores::ActiveRecord::IdentityStore.new
+      #   config.sqrl.stores = stores
+      #
+      # +FileStore+, +MemoryStore+ and +NullStore+ cannot share state between processes
+      # or delete atomically across them, so they are refused in production unless
+      # +allow_unsafe: true+ is passed.
+      module Cache
+        # Cache store classes without an atomic delete; refused in production.
+        UNSAFE_STORES = %w[ActiveSupport::Cache::FileStore ActiveSupport::Cache::MemoryStore
+                           ActiveSupport::Cache::NullStore].freeze
+
+        # @param cache [ActiveSupport::Cache::Store]
+        # @param namespace [String] key prefix
+        # @param identity_ttl [Integer, nil] seconds identities live (nil: never expire)
+        # @param allow_unsafe [Boolean] accept process-local stores in production
+        # @return [SQRL::Server::Stores]
+        def self.stores(cache = ::Rails.cache, namespace: "sqrl", identity_ttl: nil, allow_unsafe: false)
+          check!(cache, allow_unsafe: allow_unsafe)
+          SQRL::Server::Stores.new(nuts: NutStore.new(cache, namespace: namespace),
+                                   identities: IdentityStore.new(cache, namespace: namespace, ttl: identity_ttl),
+                                   pending_logins: PendingLoginStore.new(cache, namespace: namespace))
+        end
+
+        def self.check!(cache, allow_unsafe: false)
+          raise Error, "config.sqrl.cache_store must be an ActiveSupport::Cache::Store" unless cache.respond_to?(:read) && cache.respond_to?(:delete)
+          return if allow_unsafe || !defined?(::Rails) || !::Rails.respond_to?(:env) || !::Rails.env.production?
+          return unless UNSAFE_STORES.include?(cache.class.name)
+
+          raise Error, "#{cache.class.name} is process-local and cannot back SQRL stores in production; " \
+                       "use a Redis or Memcached cache store (or pass allow_unsafe: true)"
+        end
+
+        # Serialization shared by the stores: binary fields are base64url strings, times
+        # are integers, so any cache serializer (Marshal, JSON, MessagePack) works.
+        module Codec
+          module_function
+
+          # @return [String, nil] binary bytes as base64url
+          def bin(bytes) = bytes.nil? ? nil : SQRL::Util.b64u_encode(bytes.b)
+          # @return [String, nil] binary bytes from base64url
+          def unbin(text) = text.nil? ? nil : SQRL::Util.b64u_decode(text)
+          # @return [Integer, nil] a Time as epoch seconds
+          def time(value) = value&.to_i
+          # @return [Time, nil] a Time from epoch seconds
+          def untime(value) = value.nil? ? nil : Time.at(value.to_i)
+        end
+
+        # Common plumbing.
+        class Base
+          def initialize(cache, namespace:)
+            @cache = cache
+            @namespace = namespace
+          end
+
+          private
+
+          def key(*parts)
+            ([@namespace] + parts).join(":")
+          end
+
+          # Seconds until +expires_at+ (at least 1), or nil.
+          def ttl_until(expires_at, now)
+            return nil if expires_at.nil?
+
+            [(expires_at.to_i - now.to_i), 1].max
+          end
+        end
+
+        # @see SQRL::Server::NutStore
+        class NutStore < Base
+          # Issue on the cache store; same contract as +SQRL::Server::NutStore#issue+.
+          def issue(nut:, pending_login_id:, expected_server:, ip:, bound_idk:, expires_at:)
+            record = SQRL::Server::NutRecord.new(nut: nut, pending_login_id: pending_login_id,
+                                                 expected_server: expected_server, ip: ip, bound_idk: bound_idk,
+                                                 expires_at: expires_at, used_at: nil)
+            @cache.write(key("nut", nut), dump(record), expires_in: ttl_until(expires_at, Time.now))
+            record
+          end
+
+          # Consume on the cache store; same contract as +SQRL::Server::NutStore#consume+.
+          def consume(nut, now: Time.now)
+            return nil if nut.nil? || nut.empty?
+
+            data = @cache.read(key("nut", nut))
+            return nil unless data
+            # Deleting is the single-use guarantee: only one caller gets +true+.
+            return nil unless @cache.delete(key("nut", nut))
+
+            record = load(data)
+            return nil if record.expires_at && record.expires_at <= now
+
+            record.used_at = now
+            record
+          end
+
+          # Entries expire through the cache TTL.
+          def prune!(_now = Time.now)
+            nil
+          end
+
+          private
+
+          def dump(r)
+            { "nut" => r.nut, "pending_login_id" => r.pending_login_id, "expected_server" => r.expected_server,
+              "ip" => r.ip, "bound_idk" => Codec.bin(r.bound_idk), "expires_at" => Codec.time(r.expires_at) }
+          end
+
+          def load(h)
+            SQRL::Server::NutRecord.new(nut: h["nut"], pending_login_id: h["pending_login_id"],
+                                        expected_server: h["expected_server"], ip: h["ip"],
+                                        bound_idk: Codec.unbin(h["bound_idk"]),
+                                        expires_at: Codec.untime(h["expires_at"]), used_at: nil)
+          end
+        end
+
+        # @see SQRL::Server::IdentityStore
+        class IdentityStore < Base
+          def initialize(cache, namespace:, ttl: nil)
+            super(cache, namespace: namespace)
+            @ttl = ttl
+          end
+
+          # Find on the cache store; same contract as +SQRL::Server::IdentityStore#find+.
+          def find(idk)
+            data = @cache.read(key("id", Codec.bin(idk)))
+            data && load(data)
+          end
+
+          def create(**attrs)
+            identity = SQRL::Server::Identity.new(**attrs)
+            k = key("id", Codec.bin(identity.idk))
+            raise ArgumentError, "identity already exists" if @cache.exist?(k)
+
+            write(identity)
+            identity
+          end
+
+          # Update on the cache store; same contract as +SQRL::Server::IdentityStore#update+.
+          def update(idk, **attrs)
+            identity = find(idk)
+            return nil unless identity
+
+            attrs.each { |name, value| identity[name] = value }
+            write(identity)
+            identity
+          end
+
+          # Rekey on the cache store; same contract as +SQRL::Server::IdentityStore#rekey+.
+          def rekey(old_idk, new_idk, suk:, vuk:, ins:)
+            identity = find(old_idk)
+            return nil unless identity
+
+            identity.idk = new_idk
+            identity.suk = suk
+            identity.vuk = vuk
+            identity.ins = ins
+            write(identity)
+            @cache.delete(key("id", Codec.bin(old_idk)))
+            @cache.write(key("superseded", Codec.bin(old_idk)), Codec.bin(new_idk), expires_in: @ttl)
+            identity
+          end
+
+          def superseded?(idk)
+            @cache.exist?(key("superseded", Codec.bin(idk)))
+          end
+
+          # Remove on the cache store; same contract as +SQRL::Server::IdentityStore#remove+.
+          def remove(idk)
+            identity = find(idk)
+            return nil unless identity
+
+            @cache.delete(key("id", Codec.bin(idk)))
+            identity
+          end
+
+          private
+
+          def write(identity)
+            @cache.write(key("id", Codec.bin(identity.idk)), dump(identity), expires_in: @ttl)
+          end
+
+          def dump(i)
+            { "idk" => Codec.bin(i.idk), "suk" => Codec.bin(i.suk), "vuk" => Codec.bin(i.vuk),
+              "disabled" => i.disabled == true, "sqrlonly" => i.sqrlonly == true, "hardlock" => i.hardlock == true,
+              "ins" => i.ins, "logins" => i.logins.to_i, "user_ref" => i.user_ref }
+          end
+
+          def load(h)
+            SQRL::Server::Identity.new(idk: Codec.unbin(h["idk"]), suk: Codec.unbin(h["suk"]), vuk: Codec.unbin(h["vuk"]),
+                                       disabled: h["disabled"], sqrlonly: h["sqrlonly"], hardlock: h["hardlock"],
+                                       ins: h["ins"], logins: h["logins"].to_i, user_ref: h["user_ref"])
+          end
+        end
+
+        # @see SQRL::Server::PendingLoginStore
+        class PendingLoginStore < Base
+          # Create on the cache store; same contract as +SQRL::Server::PendingLoginStore#create+.
+          def create(id, ip:, return_to:, expires_at:, link_user_ref: nil, created_at: Time.now)
+            login = SQRL::Server::PendingLogin.new(id: id, ip: ip, return_to: return_to, expires_at: expires_at,
+                                                   link_user_ref: link_user_ref, created_at: created_at)
+            write(login)
+            login
+          end
+
+          # Find on the cache store; same contract as +SQRL::Server::IdentityStore#find+.
+          def find(id)
+            return nil if id.nil?
+
+            data = @cache.read(key("login", id))
+            return nil unless data
+
+            login = load(data)
+            # The cache TTL has a one-second floor; honour the exact expiry ourselves.
+            login.expires_at && login.expires_at <= Time.now ? nil : login
+          end
+
+          # Update on the cache store; same contract as +SQRL::Server::IdentityStore#update+.
+          def update(id, **attrs)
+            login = find(id)
+            return nil unless login
+
+            old_token = login.cps_token
+            attrs.each { |name, value| login[name] = value }
+            write(login)
+            if attrs.key?(:cps_token)
+              @cache.delete(key("cps", old_token)) if old_token && old_token != login.cps_token
+              if login.cps_token
+                @cache.write(key("cps", login.cps_token), id, expires_in: ttl_until(login.cps_token_expires_at, Time.now))
+              end
+            end
+            login
+          end
+
+          # Claim cps token on the cache store; same contract as +SQRL::Server::PendingLoginStore#claim_cps_token+.
+          def claim_cps_token(token, now: Time.now)
+            return nil if token.nil? || token.empty?
+
+            id = @cache.read(key("cps", token))
+            return nil unless id
+            # The index entry is the single-use guard.
+            return nil unless @cache.delete(key("cps", token))
+
+            login = find(id)
+            return nil unless login && login.cps_token == token
+
+            expired = login.cps_token_expires_at && login.cps_token_expires_at <= now
+            login.cps_token = nil
+            login.cps_token_expires_at = nil
+            write(login)
+            expired ? nil : login
+          end
+
+          # Entries expire through the cache TTL.
+          def prune!(_now = Time.now)
+            nil
+          end
+
+          private
+
+          def write(login)
+            @cache.write(key("login", login.id), dump(login), expires_in: ttl_until(login.expires_at, Time.now))
+          end
+
+          def dump(l)
+            { "id" => l.id, "authenticated_idk" => Codec.bin(l.authenticated_idk),
+              "authenticated_at" => Codec.time(l.authenticated_at), "btn" => l.btn, "asked" => l.asked == true,
+              "last_command" => l.last_command&.to_s, "cps_token" => l.cps_token,
+              "cps_token_expires_at" => Codec.time(l.cps_token_expires_at), "ip" => l.ip, "return_to" => l.return_to,
+              "link_user_ref" => l.link_user_ref, "created_at" => Codec.time(l.created_at),
+              "expires_at" => Codec.time(l.expires_at), "ip_matched" => l.ip_matched == true }
+          end
+
+          def load(h)
+            SQRL::Server::PendingLogin.new(id: h["id"], authenticated_idk: Codec.unbin(h["authenticated_idk"]),
+                                           authenticated_at: Codec.untime(h["authenticated_at"]), btn: h["btn"],
+                                           asked: h["asked"], last_command: h["last_command"]&.to_sym,
+                                           cps_token: h["cps_token"],
+                                           cps_token_expires_at: Codec.untime(h["cps_token_expires_at"]),
+                                           ip: h["ip"], return_to: h["return_to"], link_user_ref: h["link_user_ref"],
+                                           created_at: Codec.untime(h["created_at"]),
+                                           expires_at: Codec.untime(h["expires_at"]), ip_matched: h["ip_matched"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sqrl/rails/user_factory.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SQRL
+  module Rails
+    # Default +create_user+: builds a user record for a brand-new SQRL identity using
+    # only the columns the model has. SQRL carries no profile data, so placeholders are
+    # generated: a random password when the model has +password_digest+ (so
+    # +has_secure_password+ validations pass) and a non-routable email when it has an
+    # +email+ or +email_address+ column. Applications that need real data set
+    # +config.sqrl.create_user+ or use +on_unknown_identity = :link+.
+    module UserFactory
+      module_function
+
+      # @param identity [SQRL::Server::Identity]
+      # @param model [Class] the user model
+      # @return [Object] the saved user
+      def call(identity, model = SQRL::Rails.config.user_model)
+        model.create!(attributes_for(identity, model))
+      end
+
+      # @return [Hash] placeholder attributes matching the columns and writers the user model has
+      def attributes_for(identity, model)
+        columns = model.respond_to?(:column_names) ? model.column_names : []
+        handle = identity.idk_b64[0, 16].downcase.tr("_-", "xy")
+        attrs = {}
+        attrs[:email_address] = "sqrl-#{handle}@sqrl.invalid" if columns.include?("email_address")
+        attrs[:email] = "sqrl-#{handle}@sqrl.invalid" if columns.include?("email")
+        attrs[:name] = "SQRL user #{handle[0, 8]}" if columns.include?("name")
+        attrs[:username] = "sqrl-#{handle}" if columns.include?("username")
+        if model.method_defined?(:password=)
+          password = SecureRandom.hex(32)
+          attrs[:password] = password
+          attrs[:password_confirmation] = password if model.method_defined?(:password_confirmation=)
+        end
+        attrs
+      end
+    end
+  end
+end

data/lib/sqrl/rails.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "rails"
+require "sqrl/core"
+require "sqrl/rack"
+
+# SQRL namespace, reopened for the Rails integration.
+module SQRL
+  # SQRL login for Rails: an isolated engine serving the SQRL endpoint, status poll,
+  # CPS callback and browser script; ActiveRecord-backed stores; a view helper that
+  # renders the login block; and a sign-in adapter that plugs into the authentication
+  # stack generated by `bin/rails generate authentication` (Rails 8) or into any custom
+  # session scheme.
+  #
+  #   # Gemfile
+  #   gem "sqrl-rails"
+  #   # then
+  #   bin/rails generate sqrl:install
+  #   bin/rails db:migrate
+  module Rails
+    # Same as SQRL::VERSION; the gems release in lockstep.
+    VERSION = SQRL::VERSION
+
+    # Raised for configuration problems.
+    class Error < SQRL::Error; end
+
+    # Paths of the engine's routes, relative to the mount point.
+    ENGINE_PATHS = { cli: "/cli", status: "/status", callback: "/callback", login: "/login",
+                     script: "/sqrl.js", identities: "/identities", refresh: "/refresh" }.freeze
+
+    @mutex = Mutex.new
+    @host_resolver = nil
+
+    class << self
+      # The application-wide configuration (+Rails.application.config.sqrl+).
+      #
+      # @return [Configuration]
+      def config
+        ::Rails.application.config.sqrl
+      end
+
+      # The configured stores, resolved once.
+      #
+      # @return [Server::Stores]
+      def stores
+        @stores ||= resolve_stores(config.stores)
+      end
+
+      # Forget memoized handlers, endpoints and stores (tests, configuration changes).
+      def reset!
+        @mutex.synchronize do
+          @host_resolver = nil
+          @stores = nil
+          @mount_path = nil
+        end
+      end
+
+      # The {SQRL::Rack::HostResolver} deciding which host and scheme SQRL URLs are issued
+      # for, built from +config.host+, +config.scheme+, +config.allowed_hosts+ and
+      # +config.host_cache_limit+. It also bounds the per-host endpoint cache.
+      #
+      # @return [SQRL::Rack::HostResolver]
+      def host_resolver
+        @mutex.synchronize do
+          scheme = config.scheme.presence || (config.insecure_http ? "qrl" : nil)
+          @host_resolver ||= SQRL::Rack::HostResolver.new(host: config.host.presence, scheme: scheme,
+                                                          allowed_hosts: config.allowed_hosts,
+                                                          limit: config.host_cache_limit,
+                                                          logger: config.logger || ::Rails.logger)
+        end
+      end
+
+      # Path the engine is mounted at in the host application (+/sqrl+ by default).
+      def mount_path
+        config.mount_path || (@mount_path ||= detect_mount_path) || "/sqrl"
+      end
+
+      # Public (host-level) path of an engine route, for example +path_for(:status)+.
+      def path_for(name, script_name: "")
+        "#{script_name}#{mount_path}#{ENGINE_PATHS.fetch(name)}"
+      end
+
+      # The {SQRL::Rack::Endpoint} for a request's host and scheme, built lazily and
+      # memoized per [host, scheme] in a bounded cache.
+      #
+      # @param request [ActionDispatch::Request, Rack::Request]
+      # @return [SQRL::Rack::Endpoint]
+      # @raise [SQRL::Rack::HostNotAllowed] when the request host may not be used
+      def endpoint_for(request)
+        resolver = host_resolver
+        host, scheme = resolver.resolve(request)
+        resolver.fetch([host, scheme]) { build_endpoint(host, scheme) }
+      end
+
+      # The {Server::Handler} for a request (see {endpoint_for}).
+      def handler_for(request)
+        endpoint_for(request).handler
+      end
+
+      # Whether any active SQRL identity of +user+ asked the site to disable every other
+      # (non-SQRL) way of authenticating (+opt=sqrlonly+). Password logins for such a
+      # user must be refused; see {PasswordPolicy}.
+      #
+      # @param user [Object, nil]
+      # @return [Boolean]
+      def sqrl_only?(user)
+        return false if user.nil?
+
+        Identity.active.for_user(user).where(sqrlonly: true).exists?
+      end
+
+      # Whether any active SQRL identity of +user+ asked the site to disable every other
+      # (non-SQRL) way of recovering the account (+opt=hardlock+). Password resets for
+      # such a user must be refused; see {PasswordPolicy}.
+      #
+      # @param user [Object, nil]
+      # @return [Boolean]
+      def hard_locked?(user)
+        return false if user.nil?
+
+        Identity.active.for_user(user).where(hardlock: true).exists?
+      end
+
+      # Opaque reference stored on SQRL identities to point at the application's user:
+      # +"User:42"+.
+      def user_ref(user)
+        return nil if user.nil?
+        return user if user.is_a?(String)
+
+        type = user.class.respond_to?(:polymorphic_name) ? user.class.polymorphic_name : user.class.name
+        "#{type}:#{user.id}"
+      end
+
+      # Resolve a reference made by {user_ref} back to the record, or nil.
+      def user_from_ref(ref)
+        return nil if ref.blank?
+
+        type, id = ref.to_s.split(":", 2)
+        return nil if type.blank? || id.blank?
+
+        klass = type.safe_constantize
+        return nil unless klass.respond_to?(:find_by)
+
+        klass.find_by(klass.primary_key => id)
+      end
+
+      # The host application's +Authentication+ concern from `rails generate
+      # authentication`, when present.
+      #
+      # @return [Module, nil]
+      def host_authentication_concern
+        return nil unless Object.const_defined?(:Authentication)
+
+        concern = Object.const_get(:Authentication)
+        if (concern.is_a?(Module) && concern.method_defined?(:start_new_session_for, false)) ||
+           (concern.is_a?(Module) && concern.private_method_defined?(:start_new_session_for, false))
+          concern
+        end
+      rescue NameError
+        nil
+      end
+
+      private
+
+      def resolve_stores(value)
+        case value
+        when nil, :active_record, "active_record" then Stores::ActiveRecord.stores
+        when :memory, "memory" then Server::Memory.stores
+        when :cache, "cache" then Stores::Cache.stores(config.cache_store || ::Rails.cache)
+        when Server::Stores then value
+        else
+          raise Error, "config.sqrl.stores must be :active_record, :cache, :memory or an SQRL::Server::Stores"
+        end
+      end
+
+      def build_endpoint(host, scheme)
+        mount = mount_path
+        server_config = Server::Config.new(**config.server_options, host: host, scheme: scheme,
+                                                                    path: "#{mount}#{ENGINE_PATHS[:cli]}",
+                                                                    callback_path: "#{mount}#{ENGINE_PATHS[:callback]}")
+        handler = Server::Handler.new(config: server_config, stores: stores)
+        SQRL::Rack::Endpoint.new(handler: handler, session_key: config.session_key, identity_key: config.identity_key,
+                                 status_path: ENGINE_PATHS[:status], callback_path: ENGINE_PATHS[:callback],
+                                 script_path: ENGINE_PATHS[:script], refresh_path: ENGINE_PATHS[:refresh],
+                                 poll_requires_ip_match: config.poll_requires_ip_match ? true : false,
+                                 ip: config.ip || method(:client_ip))
+      end
+
+      def client_ip(request)
+        request.respond_to?(:remote_ip) ? request.remote_ip : request.ip
+      end
+
+      # Find where the host application mounted the engine.
+      def detect_mount_path
+        ::Rails.application.routes.routes.each do |route|
+          app = route.app
+          # A mount is wrapped in ActionDispatch::Routing::Mapper::Constraints; plain
+          # dispatchers return themselves from #app.
+          app = app.app if app.respond_to?(:app) && !app.equal?(app.app)
+          next unless app == Engine
+
+          return route.path.spec.to_s.sub(/\(\.:format\)\z/, "").sub(%r{/\z}, "")
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end
+
+require_relative "rails/configuration"
+require_relative "rails/stores/active_record"
+require_relative "rails/stores/cache"
+require_relative "rails/user_factory"
+require_relative "rails/sign_in"
+require_relative "rails/controller_helpers"
+require_relative "rails/password_policy"
+require_relative "rails/rate_limited"
+require_relative "rails/engine"

data/lib/sqrl-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sqrl/rails"

data/lib/tasks/sqrl.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+namespace :sqrl do
+  desc "Delete expired SQRL nuts and pending logins"
+  task prune: :environment do
+    stores = SQRL::Rails.stores
+    now = Time.current
+    stores.nuts.prune!(now)
+    stores.pending_logins.prune!(now)
+    puts "SQRL: pruned expired nuts and pending logins"
+  end
+end