sqrl-rack 0.1.0

data/lib/sqrl/rack/middleware.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rack
+    # Rack middleware that mounts SQRL login in any Rack application.
+    #
+    #   use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET")
+    #   use SQRL::Rack::Middleware,
+    #       stores: SQRL::Server::Memory.stores,
+    #       host: "example.com",
+    #       on_login: ->(env, identity, pending_login) { env["rack.session"]["user_id"] = User.for_sqrl(identity).id },
+    #       after_login: "/"
+    #
+    # It answers +POST path+ (the SQRL endpoint; never reaches the app, so no CSRF layer
+    # sees it), +GET status_path+, +GET callback_path+ and +GET script_path+, and exposes
+    # +env["sqrl.server"]+ (a {Facade}) to everything else.
+    #
+    # Options: every {Server::Config} keyword (+host+ defaults to the request host;
+    # +scheme+ is always +sqrl+; +insecure_http: true+ switches a loopback-only site to
+    # +qrl://+ for testing with the browser extension's test server) plus
+    # +stores:+, +status_path:+, +script_path:+, +session_key:+, +identity_key:+,
+    # +ip:+ (callable resolving the client IP), +on_login:+ (callable
+    # +(env, identity, pending_login)+), +after_login:+ (path, URL or callable
+    # +(env, completion) -> String+; a same-site +return_to+ recorded on the pending login
+    # wins), +failure_path:+ (redirect target when the callback fails; 403 when nil),
+    # +session_identity:+ (store the +idk+ in the session; defaults to true when
+    # +on_login+ is nil), +refresh_path:+ (JSON endpoint handing the page a fresh login
+    # URL), +allowed_hosts:+ and +host_cache_limit:+ (see {HostResolver}; derived hosts
+    # beyond the limit get 400), and the rate-limit hooks +before_issue:+ /
+    # +before_handle:+ (see {Server::Config}; a hook raising {Server::RateLimited} turns
+    # into HTTP 429).
+    class Middleware
+      # Option defaults.
+      DEFAULTS = {
+        path: "/sqrl/cli", callback_path: "/sqrl/callback", status_path: "/sqrl/status", script_path: "/sqrl/sqrl.js",
+        refresh_path: "/sqrl/refresh", session_key: Endpoint::SESSION_KEY, identity_key: Endpoint::IDENTITY_KEY,
+        after_login: "/"
+      }.freeze
+      # Options consumed by {Endpoint} rather than {SQRL::Server::Config}.
+      ENDPOINT_KEYS = %i[status_path script_path refresh_path session_key identity_key ip poll_requires_ip_match].freeze
+      # Options consumed by the middleware itself.
+      MIDDLEWARE_KEYS = %i[stores on_login after_login failure_path session_identity host_cache_limit].freeze
+
+      # @param app [#call]
+      # @param options [Hash, #call] options, or a callable returning them (resolved on
+      #   the first request, which lets a Sinatra app finish its +set+ calls first)
+      def initialize(app, options = {})
+        @app = app
+        @raw_options = options
+        @mutex = Mutex.new
+      end
+
+      # Rack entry point.
+      # @param env [Hash]
+      # @return [Array] a Rack response triple
+      def call(env)
+        request = ::Rack::Request.new(env)
+        endpoint = endpoint_for(request)
+        path = request.path_info
+        if request.post? && path == options[:path]
+          endpoint.cli(request)
+        elsif request.get? && path == endpoint.status_path
+          endpoint.status(request)
+        elsif request.get? && path == endpoint.callback_path
+          complete(endpoint, request)
+        elsif request.get? && path == endpoint.script_path
+          endpoint.script(request)
+        elsif request.get? && path == endpoint.refresh_path
+          endpoint.refresh(request)
+        else
+          env["sqrl.server"] = Facade.new(endpoint, request)
+          @app.call(env)
+        end
+      rescue HostNotAllowed => e
+        [400, { "content-type" => "text/plain; charset=utf-8", "cache-control" => "no-store" }, ["#{e.message}\n"]]
+      end
+
+      # Resolved options (frozen).
+      def options
+        @options ||= @mutex.synchronize do
+          @options || begin
+            raw = @raw_options.respond_to?(:call) ? @raw_options.call : @raw_options
+            DEFAULTS.merge((raw || {}).transform_keys(&:to_sym)).freeze
+          end
+        end
+      end
+
+      # The shared stores.
+      def stores
+        @stores ||= options[:stores] || Server::Memory.stores
+      end
+
+      # The {HostResolver} deciding host and scheme per request and bounding the
+      # per-host endpoint cache.
+      def host_resolver
+        return @host_resolver if @host_resolver
+
+        opts = options # resolved outside the lock: it takes the same mutex
+        @mutex.synchronize do
+          scheme = opts[:scheme] || (opts[:insecure_http] ? "qrl" : nil)
+          @host_resolver ||= HostResolver.new(host: opts[:host], scheme: scheme,
+                                              allowed_hosts: opts[:allowed_hosts],
+                                              limit: opts[:host_cache_limit], logger: opts[:logger])
+        end
+      end
+
+      # One {Endpoint} per (host, scheme, mount prefix) combination, built lazily.
+      #
+      # @raise [HostNotAllowed] when the request host is not acceptable
+      def endpoint_for(request)
+        host, scheme = host_resolver.resolve(request)
+        prefix = request.script_name.to_s
+        host_resolver.fetch([host, scheme, prefix]) { build_endpoint(host, scheme, prefix) }
+      end
+
+      private
+
+      def build_endpoint(host, scheme, prefix)
+        config_opts = options.reject { |k, _| ENDPOINT_KEYS.include?(k) || MIDDLEWARE_KEYS.include?(k) }
+        config_opts[:host] = host
+        config_opts[:scheme] = scheme
+        config_opts[:path] = prefix + options[:path]
+        config_opts[:callback_path] = prefix + options[:callback_path]
+        config = Server::Config.new(**config_opts)
+        handler = Server::Handler.new(config: config, stores: stores)
+        Endpoint.new(handler: handler, session_key: options[:session_key], identity_key: options[:identity_key],
+                     status_path: options[:status_path], callback_path: options[:callback_path],
+                     script_path: options[:script_path], refresh_path: options[:refresh_path], ip: options[:ip],
+                     poll_requires_ip_match: options.fetch(:poll_requires_ip_match, false))
+      end
+
+      def complete(endpoint, request)
+        completion = endpoint.callback(request)
+        return failure(request) unless completion
+
+        env = request.env
+        on_login = options[:on_login]
+        keep = options.fetch(:session_identity, on_login.nil?)
+        env["rack.session"].delete(endpoint.identity_key) unless keep
+        on_login&.call(env, completion.identity, completion.pending_login)
+        redirect(after_login_url(request, completion))
+      end
+
+      def after_login_url(request, completion)
+        return_to = completion.return_to
+        return return_to if same_site_path?(return_to)
+
+        target = options[:after_login]
+        target = target.call(request.env, completion) if target.respond_to?(:call)
+        target.to_s.empty? ? "#{request.script_name}/" : target
+      end
+
+      # A same-site, root-relative path. Rejects protocol-relative URLs (//host), the
+      # backslash form browsers normalise to a slash (/\host), and control characters or
+      # whitespace that URL parsers strip before interpreting the rest.
+      def same_site_path?(path)
+        path.is_a?(String) && path.match?(%r{\A/(?![/\\])}) && !path.match?(/[\x00-\x20\x7f\\]/)
+      end
+
+      def failure(_request)
+        if options[:failure_path]
+          redirect(options[:failure_path])
+        else
+          [403, { "content-type" => "text/plain; charset=utf-8", "cache-control" => "no-store" },
+           ["SQRL login failed or expired. Reload the login page and try again."]]
+        end
+      end
+
+      def redirect(location)
+        [303, { "location" => location, "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store" },
+         [%(<!doctype html><title>Redirecting</title><a href="#{CGI.escapeHTML(location)}">Continue</a>)]]
+      end
+    end
+  end
+end

data/lib/sqrl/rack/qr.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rqrcode"
+require "cgi"
+
+module SQRL
+  module Rack
+    # QR code rendering for +sqrl://+ URLs.
+    module QR
+      module_function
+
+      # Render +url+ as an accessible SVG QR code.
+      #
+      # @param url [String] the login URL
+      # @param size [Integer] rendered width and height in CSS pixels (ignored when
+      #   +module_size+ is given)
+      # @param module_size [Integer, nil] pixels per QR module
+      # @param color [String] foreground colour
+      # @param background [String] background colour
+      # @param title [String] accessible name
+      # @param quiet_zone [Integer] modules of margin around the code
+      # @param level [Symbol] error correction level (:l, :m, :q, :h)
+      # @return [String] an +<svg role="img">+ element
+      def svg(url, size: 256, module_size: nil, color: "#000000", background: "#ffffff",
+              title: "SQRL login QR code", quiet_zone: 4, level: :m)
+        modules = RQRCode::QRCode.new(url.to_s, level: level).modules
+        count = modules.length
+        total = count + (quiet_zone * 2)
+        pixels = module_size ? module_size * total : size
+        path = +""
+        modules.each_with_index do |row, y|
+          row.each_with_index do |dark, x|
+            path << "M#{x + quiet_zone} #{y + quiet_zone}h1v1h-1z" if dark
+          end
+        end
+        <<~SVG.strip
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{total} #{total}" width="#{pixels}" height="#{pixels}" role="img" aria-label="#{h(title)}" shape-rendering="crispEdges" class="sqrl-qr"><title>#{h(title)}</title><rect width="#{total}" height="#{total}" fill="#{h(background)}"/><path d="#{path}" fill="#{h(color)}"/></svg>
+        SVG
+      end
+
+      # Render +url+ as PNG bytes (needs the +chunky_png+ gem that +rqrcode+ depends on).
+      #
+      # @return [String] binary PNG data
+      def png(url, size: 256, level: :m)
+        RQRCode::QRCode.new(url.to_s, level: level).as_png(size: size, border_modules: 4).to_s
+      end
+
+      def h(str)
+        CGI.escapeHTML(str.to_s)
+      end
+      private_class_method :h
+    end
+  end
+end

data/lib/sqrl/rack.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rack"
+require "sqrl/core"
+
+module SQRL
+  # SQRL login for Rack applications: the framework-neutral {Endpoint}, the {Middleware}
+  # that mounts it, the per-request {Facade} for applications, the login markup
+  # ({LoginBlock}), QR rendering ({QR}) and the browser script ({Assets}).
+  module Rack
+    # Same as SQRL::VERSION; the gems release in lockstep.
+    VERSION = SQRL::VERSION
+
+    # Raised for configuration problems (for example a missing session middleware).
+    class Error < SQRL::Error; end
+  end
+end
+
+require_relative "rack/host_resolver"
+require_relative "rack/assets"
+require_relative "rack/qr"
+require_relative "rack/login_block"
+require_relative "rack/endpoint"
+require_relative "rack/facade"
+require_relative "rack/middleware"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: sqrl-rack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel P. Clark
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rqrcode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqrl-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Rack middleware serving the SQRL endpoint, status poll and CPS callback,
+  a Sinatra extension with view helpers, the browser-side script and QR code rendering.
+email:
+- 6ftdan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- assets/sqrl.js
+- lib/roda/plugins/sqrl.rb
+- lib/sinatra/sqrl.rb
+- lib/sqrl/rack.rb
+- lib/sqrl/rack/assets.rb
+- lib/sqrl/rack/endpoint.rb
+- lib/sqrl/rack/facade.rb
+- lib/sqrl/rack/host_resolver.rb
+- lib/sqrl/rack/login_block.rb
+- lib/sqrl/rack/middleware.rb
+- lib/sqrl/rack/qr.rb
+homepage: https://github.com/danielpclark/sqrl-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/danielpclark/sqrl-ruby
+  source_code_uri: https://github.com/danielpclark/sqrl-ruby/tree/main/gems/sqrl-rack
+  changelog_uri: https://github.com/danielpclark/sqrl-ruby/blob/main/gems/sqrl-rack/CHANGELOG.md
+  bug_tracker_uri: https://github.com/danielpclark/sqrl-ruby/issues
+  documentation_uri: https://github.com/danielpclark/sqrl-ruby/blob/main/gems/sqrl-rack/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: SQRL login for Rack applications and Sinatra
+test_files: []