sqrl-rack 0.1.0

data/lib/sqrl/rack/endpoint.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SQRL
+  module Rack
+    # Framework-neutral request handlers around a {Server::Handler}: issue login URLs,
+    # answer the SQRL client's POST, the browser's status poll and the login callback.
+    # {Middleware} drives these for plain Rack; the Rails engine calls them from
+    # controllers.
+    #
+    # The pending login id lives in the browser session under +session_key+; the
+    # identity of a completed login is written under +identity_key+ by {#callback}.
+    class Endpoint
+      # Default session key holding the pending-login id.
+      SESSION_KEY = "sqrl.pending_login"
+      # Default session key holding the logged-in identity key (base64url).
+      IDENTITY_KEY = "sqrl.identity"
+
+      # What {#callback} returns when a login completes.
+      Completion = Struct.new(:identity, :pending_login, :via, keyword_init: true) do
+        # @return [String] the identity key as base64url
+        def idk_b64 = identity.idk_b64
+        # @return [String, nil] the same-site return path captured when the login page was issued
+        def return_to = pending_login.return_to
+        def cps? = via == :cps
+      end
+
+      attr_reader :handler, :config, :session_key, :identity_key, :status_path, :callback_path, :script_path,
+                  :refresh_path
+
+      # Headers of a 429 answer.
+      RATE_LIMITED_HEADERS = { "content-type" => "text/plain; charset=utf-8", "cache-control" => "no-store" }.freeze
+
+      # @param handler [Server::Handler]
+      # @param status_path [String] app-relative path of the JSON poll endpoint
+      # @param callback_path [String] app-relative path of the login callback
+      #   (+config.callback_path+ must be the public form of the same path)
+      # @param script_path [String] app-relative path serving +sqrl.js+
+      # @param ip [#call, nil] +(request) -> String+ resolving the client IP; defaults to
+      #   +Rack::Request#ip+
+      # +poll_requires_ip_match+ (default false): when true, a login completed through the
+      # browser's own cookie (the poll path, no CPS token) counts only when the SQRL
+      # client's IP matched the browser's. This is an optional hardening against a client
+      # that sent +noiptest+ being tricked into authenticating a login page opened by
+      # someone else; it also refuses legitimate logins from a phone on another network,
+      # which is why it is off by default. CPS completions are unaffected.
+      # +refresh_path+ serves {#refresh}: a JSON endpoint the page calls (through
+      # +SQRL.refresh+) to swap an expired login URL for a fresh one without a reload.
+      def initialize(handler:, session_key: SESSION_KEY, identity_key: IDENTITY_KEY, status_path: "/sqrl/status",
+                     callback_path: nil, script_path: "/sqrl/sqrl.js", refresh_path: "/sqrl/refresh", ip: nil,
+                     poll_requires_ip_match: false)
+        @handler = handler
+        @refresh_path = refresh_path
+        @poll_requires_ip_match = poll_requires_ip_match
+        @config = handler.config
+        @session_key = session_key
+        @identity_key = identity_key
+        @status_path = status_path
+        @callback_path = callback_path || handler.config.callback_path
+        @script_path = script_path
+        @ip = ip
+      end
+
+      # Issue a fresh login URL and remember its pending login in the browser session.
+      #
+      # @param request [Rack::Request]
+      # @param return_to [String, nil] where the browser goes after login (same-site path)
+      # @param cancel_url [String, nil] encoded into +can=+
+      # @param link_user_ref [Object, nil] signed-in user to link a new identity to
+      # @return [Server::LoginURL]
+      def issue(request, return_to: nil, cancel_url: nil, link_user_ref: nil)
+        session = session_of(request)
+        login = @handler.new_login_url(ip: client_ip(request), cancel_url: cancel_url, return_to: return_to,
+                                       link_user_ref: link_user_ref)
+        session[@session_key] = login.pending_login_id
+        login
+      end
+
+      # The pending login id stored in the browser session, if any.
+      def pending_login_id(request)
+        session = request.env["rack.session"]
+        session && session[@session_key]
+      end
+
+      # Handle the SQRL client's POST. Always 200 with the protocol body; TIF carries
+      # failures.
+      #
+      # @return [Array] a Rack response triple
+      def cli(request)
+        result = @handler.handle(nut: request.GET["nut"].to_s, body: form_body(request), ip: client_ip(request))
+        [200, { "content-type" => "text/plain; charset=utf-8", "cache-control" => "no-store",
+                "x-sqrl-tif" => result.tif.to_hex }, [result.body]]
+      rescue Server::RateLimited => e
+        rate_limited(e)
+      end
+
+      # The 429 response for a {Server::RateLimited} raised by a hook.
+      #
+      # @return [Array] a Rack response triple
+      def rate_limited(error, json: false)
+        headers = RATE_LIMITED_HEADERS.dup
+        headers["retry-after"] = error.retry_after.to_i.to_s if error.retry_after
+        body = json ? JSON.generate(error: "rate_limited", message: error.message) : "#{error.message}\n"
+        headers["content-type"] = "application/json; charset=utf-8" if json
+        [429, headers, [body]]
+      end
+
+      # Hand the page a fresh login URL for its browser session (a new pending login and
+      # nut, carrying over +return_to+ and the link target of the previous one), as JSON:
+      # +{"sqrl_url", "status_url", "qr_svg"}+. +qr=0+ leaves the QR code out.
+      #
+      # @return [Array] a Rack response triple
+      def refresh(request)
+        previous_id = pending_login_id(request)
+        previous = previous_id && @handler.stores.pending_logins.find(previous_id)
+        login = issue(request, return_to: previous&.return_to, link_user_ref: previous&.link_user_ref)
+        payload = { sqrl_url: login.url, status_url: status_url(request), refresh_url: refresh_url(request) }
+        payload[:qr_svg] = QR.svg(login.url) unless request.GET["qr"] == "0"
+        [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" },
+         [JSON.generate(payload)]]
+      rescue Server::RateLimited => e
+        rate_limited(e, json: true)
+      end
+
+      # Answer the browser's poll with JSON.
+      #
+      # @return [Array] a Rack response triple
+      def status(request)
+        id = pending_login_id(request)
+        payload =
+          if id.nil?
+            { authenticated: false }
+          else
+            login = @handler.stores.pending_logins.find(id)
+            if login.nil? || login.expired?(@config.now)
+              { authenticated: false, expired: true }
+            elsif login.authenticated? && poll_completable?(login)
+              { authenticated: true, next: callback_url(request) }
+            else
+              { authenticated: false }
+            end
+          end
+        [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" },
+         [JSON.generate(payload)]]
+      end
+
+      # Complete a login. With a +t=+ token (CPS) the token is claimed once and must
+      # belong to this browser's pending login; without one, the browser's own pending
+      # login is completed if the SQRL client authenticated it. Either way the pending
+      # login is detached from the session so it completes at most once. On success the
+      # identity's +idk+ is stored under +identity_key+.
+      #
+      # @return [Completion, nil]
+      def callback(request)
+        session = session_of(request)
+        token = request.GET["t"]
+        expected_id = session[@session_key]
+        login, via =
+          if token && !token.empty?
+            [@handler.claim_cps(token), :cps]
+          else
+            [expected_id && @handler.stores.pending_logins.find(expected_id), :poll]
+          end
+        return nil if login.nil? || expected_id.nil? || !Util.secure_compare(login.id.to_s, expected_id.to_s)
+        return nil unless login.authenticated? && !login.expired?(@config.now)
+        return nil if via == :poll && !poll_completable?(login)
+
+        identity = @handler.stores.identities.find(login.authenticated_idk)
+        return nil if identity.nil? || identity.disabled?
+
+        session.delete(@session_key)
+        session[@identity_key] = identity.idk_b64
+        Completion.new(identity: identity, pending_login: login, via: via)
+      end
+
+      # Whether a pending login may be completed without a CPS token.
+      def poll_completable?(login)
+        !@poll_requires_ip_match || login.ip_matched == true
+      end
+
+      # The identity currently logged in through SQRL in this browser session, or nil.
+      def current_identity(request)
+        session = request.env["rack.session"]
+        idk_b64 = session && session[@identity_key]
+        return nil unless idk_b64
+
+        @handler.stores.identities.find(Util.b64u_decode(idk_b64.to_s))
+      rescue FormatError
+        nil
+      end
+
+      # Forget the SQRL login and any pending login in this browser session.
+      def logout(request)
+        session = request.env["rack.session"]
+        return unless session
+
+        session.delete(@identity_key)
+        session.delete(@session_key)
+        nil
+      end
+
+      # Serve +sqrl.js+.
+      #
+      # @return [Array] a Rack response triple
+      def script(request)
+        etag = %("#{Assets.javascript_digest}")
+        if request.env["HTTP_IF_NONE_MATCH"] == etag
+          return [304, { "etag" => etag, "cache-control" => "public, max-age=86400" }, []]
+        end
+
+        [200, { "content-type" => "application/javascript; charset=utf-8", "etag" => etag,
+                "cache-control" => "public, max-age=86400" }, [Assets.javascript]]
+      end
+
+      # Browser-facing URLs, honouring the mount prefix (+SCRIPT_NAME+).
+      def status_url(request) = prefixed(request, @status_path)
+      # @return [String] path of the callback for this request (mount prefix included)
+      def callback_url(request) = prefixed(request, @callback_path)
+      # @return [String] path of +sqrl.js+ for this request (mount prefix included)
+      def script_url(request) = prefixed(request, @script_path)
+      # @return [String] path of the refresh endpoint for this request (mount prefix included)
+      def refresh_url(request) = prefixed(request, @refresh_path)
+
+      # The client IP a request comes from.
+      def client_ip(request)
+        (@ip ? @ip.call(request) : request.ip).to_s
+      end
+
+      private
+
+      # The POST body. Middleware upstream (Rack::Protection, parameter parsers) may
+      # already have consumed +rack.input+ without rewinding it, so a form body is rebuilt
+      # from Rack's cached form hash; SQRL values are base64url, which the form decoding
+      # leaves untouched.
+      def form_body(request)
+        if request.form_data? && request.POST.any?
+          request.POST.map { |k, v| "#{k}=#{v}" }.join("&")
+        else
+          body = request.body
+          body.rewind if body.respond_to?(:rewind)
+          data = body.read.to_s
+          body.rewind if body.respond_to?(:rewind)
+          data
+        end
+      rescue StandardError
+        ""
+      end
+
+      def prefixed(request, path)
+        "#{request.script_name}#{path}"
+      end
+
+      def session_of(request)
+        session = request.env["rack.session"]
+        return session if session
+
+        raise Error, "SQRL::Rack needs a session: add a session middleware (for example " \
+                     "Rack::Session::Cookie) before SQRL::Rack::Middleware, or `enable :sessions` in Sinatra"
+      end
+    end
+  end
+end

data/lib/sqrl/rack/facade.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rack
+    # Request-scoped view of SQRL for the application, available as
+    # +env["sqrl.server"]+ on every request the {Middleware} passes through.
+    class Facade
+      attr_reader :endpoint, :request
+
+      def initialize(endpoint, request)
+        @endpoint = endpoint
+        @request = request
+      end
+
+      # The login URL for this page view (issued once per request).
+      #
+      # @return [Server::LoginURL]
+      def login_url(return_to: nil, cancel_url: nil, link_user_ref: nil)
+        @login_url ||= @endpoint.issue(@request, return_to: return_to, cancel_url: cancel_url,
+                                                 link_user_ref: link_user_ref)
+      end
+
+      # Full login markup (link, QR, status text, script tag). Options are those of
+      # {LoginBlock.render} plus +return_to:+, +link_user_ref:+ and +script:+ (false to
+      # leave the script tag out).
+      #
+      # When a +before_issue+ hook refuses the request ({Server::RateLimited}) the block
+      # degrades to a short "try again later" message instead of raising.
+      def login_block(return_to: nil, cancel_url: nil, link_user_ref: nil, script: true, **options)
+        login = login_url(return_to: return_to, cancel_url: cancel_url, link_user_ref: link_user_ref)
+        LoginBlock.render(login_url: login.url, status_url: @endpoint.status_url(@request),
+                          cancel_url: cancel_url, script_url: script ? @endpoint.script_url(@request) : nil,
+                          refresh_url: @endpoint.refresh_url(@request), **options)
+      rescue Server::RateLimited => e
+        LoginBlock.unavailable(message: e.message, css_class: options.fetch(:css_class, "sqrl-login"))
+      end
+
+      # @return [String] a +<script>+ tag loading +sqrl.js+ from this site
+      def script_tag
+        LoginBlock.script_tag(src: @endpoint.script_url(@request))
+      end
+
+      # @return [String] the login URL as an SVG QR code (see {QR.svg})
+      def qr_svg(**options)
+        QR.svg(login_url.url, **options)
+      end
+
+      # @return [String] see {Endpoint#status_url}
+      def status_url = @endpoint.status_url(@request)
+      # @return [String] see {Endpoint#callback_url}
+      def callback_url = @endpoint.callback_url(@request)
+      # @return [String] see {Endpoint#script_url}
+      def script_url = @endpoint.script_url(@request)
+      # @return [String] see {Endpoint#refresh_url}
+      def refresh_url = @endpoint.refresh_url(@request)
+
+      # The SQRL identity record logged in to this browser session, or nil.
+      def identity
+        return @identity if defined?(@identity)
+
+        @identity = @endpoint.current_identity(@request)
+      end
+
+      # @return [String, nil] the logged-in identity key as base64url
+      def idk_b64 = identity&.idk_b64
+
+      def authenticated?
+        !identity.nil?
+      end
+
+      # Forget the SQRL login in this session.
+      def logout!
+        @endpoint.logout(@request)
+        remove_instance_variable(:@identity) if defined?(@identity)
+        nil
+      end
+    end
+  end
+end

data/lib/sqrl/rack/host_resolver.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rack
+    # Raised when a request's host may not be used to issue SQRL URLs. Integrations answer
+    # 400.
+    class HostNotAllowed < Error; end
+
+    # Decides which host (with port) and scheme a request's SQRL URLs are issued for, and
+    # bounds the set of hosts an integration keeps per-host state for.
+    #
+    # The host is the string every identity key is derived from, so a deployment should
+    # configure it explicitly. When it is not configured the request's +Host+ header is
+    # used: a warning is logged once, the host must pass +allowed_hosts+ when that list is
+    # given, and at most +limit+ distinct hosts are accepted per process; further ones
+    # raise {HostNotAllowed} rather than growing the per-host caches without bound.
+    #
+    # {#fetch} is the bounded, thread-safe cache integrations keep their per-host handler
+    # or endpoint in; a configured host never counts against the limit.
+    class HostResolver
+      # Default number of distinct derived hosts the handler cache holds.
+      DEFAULT_LIMIT = 16
+
+      attr_reader :host, :scheme, :limit
+
+      # @param host [String, nil] the configured public host (with port), or nil to derive
+      # @param scheme [String, nil] +sqrl+ (the default and the only standard scheme) or
+      #   +qrl+ for the loopback-only +insecure_http+ testing mode; never derived from the request
+      # @param allowed_hosts [Array<String, Regexp>, nil] accepted derived hosts
+      # @param limit [Integer] maximum number of distinct derived hosts kept
+      # @param logger [#warn, nil] receives the one-time warning; +Kernel#warn+ when nil
+      def initialize(host: nil, scheme: nil, allowed_hosts: nil, limit: DEFAULT_LIMIT, logger: nil)
+        @host = host&.to_s
+        @scheme = scheme&.to_s
+        @allowed_hosts = allowed_hosts
+        @limit = limit || DEFAULT_LIMIT
+        @logger = logger
+        @mutex = Mutex.new
+        @cache = {}
+        @warned = false
+      end
+
+      # @return [Boolean] whether the host comes from configuration rather than requests
+      def configured?
+        !@host.nil? && !@host.empty?
+      end
+
+      # The host (with port) and scheme for a request.
+      #
+      # @param request [Rack::Request]
+      # @return [Array(String, String)]
+      # @raise [HostNotAllowed] when a derived host is not allowed
+      def resolve(request)
+        host = configured? ? @host : derived_host(request)
+        [host, @scheme || "sqrl"]
+      end
+
+      # Fetch (or build with the block) the cached object for +key+, whose first element
+      # must be the host. Once +limit+ distinct derived hosts are cached, a key for a new
+      # host raises {HostNotAllowed} (keys for already-known hosts, for example other
+      # mount prefixes, are still accepted).
+      def fetch(key)
+        @mutex.synchronize do
+          return @cache[key] if @cache.key?(key)
+
+          host = host_of(key)
+          if !configured? && known_hosts.size >= @limit && !known_hosts.include?(host)
+            raise HostNotAllowed, "too many distinct request hosts (limit #{@limit}); configure host: explicitly"
+          end
+
+          @cache[key] = yield
+        end
+      end
+
+      # Distinct hosts currently cached.
+      def known_hosts
+        @cache.keys.map { |k| host_of(k) }.uniq
+      end
+
+      # Number of cached entries.
+      def size
+        @mutex.synchronize { @cache.size }
+      end
+
+      # Whether +host+ (with or without port) passes +allowed_hosts+ (always when none).
+      def allowed?(host)
+        Server::Config.new(host: "placeholder.invalid", allowed_hosts: @allowed_hosts).host_allowed?(host)
+      end
+
+      private
+
+      def host_of(key)
+        key.is_a?(Array) ? key.first : key
+      end
+
+      def derived_host(request)
+        host = request.host_with_port.to_s
+        raise HostNotAllowed, "request has no Host" if host.empty?
+        raise HostNotAllowed, "host #{host.inspect} is not in allowed_hosts" unless allowed?(host)
+
+        warn_once(host)
+        host
+      end
+
+      def warn_once(host)
+        return if @warned
+
+        @warned = true
+        message = "[sqrl] host not configured; deriving it from the request (#{host}). Identities are keyed " \
+                  "by host, so set host: explicitly in production."
+        @logger.respond_to?(:warn) ? @logger.warn(message) : Kernel.warn(message)
+      end
+    end
+  end
+end

data/lib/sqrl/rack/login_block.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module SQRL
+  module Rack
+    # Framework-neutral HTML for a SQRL login: the link, the QR code and the status text
+    # that +sqrl.js+ drives. Every framework integration renders this.
+    module LoginBlock
+      # Default status texts, overridable through +texts:+.
+      DEFAULT_TEXTS = {
+        message: "Scan the code with your SQRL client, or click the link if it is on this device.",
+        cps: "Local SQRL client detected.",
+        done: "Logged in, redirecting…",
+        expired: "This login code expired. Reload the page to get a new one.",
+        refresh: "Get a new code",
+        unavailable: "SQRL login is temporarily unavailable. Please try again in a moment."
+      }.freeze
+
+      module_function
+
+      # @param login_url [String, #to_s] the +sqrl://+ URL (a {Server::LoginURL} works)
+      # @param status_url [String] cookie-bound poll endpoint
+      # @param cancel_url [String, nil] renders a cancel link when given
+      # @param qr [Boolean] include the QR code
+      # @param qr_options [Hash] passed to {QR.svg}
+      # @param link_text [String]
+      # @param cancel_text [String]
+      # @param texts [Hash] overrides for {DEFAULT_TEXTS} (+:message+, +:cps+, +:done+, +:expired+)
+      # @param css_class [String] class of the root element (BEM children derive from it)
+      # @param poll_ms [Integer] poll interval
+      # @param script_url [String, nil] when given, a deferred +<script src>+ is appended
+      # @param refresh_url [String, nil] JSON endpoint +sqrl.js+ calls to replace an
+      #   expired login URL in place (renders a hidden "Get a new code" button)
+      # @param extra_attrs [Hash] extra attributes on the root element
+      # @return [String] HTML
+      def render(login_url:, status_url:, cancel_url: nil, qr: true, qr_options: {}, link_text: "Sign in with SQRL",
+                 cancel_text: "Cancel", texts: {}, css_class: "sqrl-login", poll_ms: 2000, script_url: nil,
+                 refresh_url: nil, extra_attrs: {})
+        url = login_url.to_s
+        t = DEFAULT_TEXTS.merge(texts)
+        attrs = {
+          "class" => css_class, "data-sqrl-login" => "", "data-sqrl-url" => url, "data-sqrl-status" => status_url,
+          "data-sqrl-poll" => poll_ms.to_i, "data-sqrl-text-message" => t[:message], "data-sqrl-text-cps" => t[:cps],
+          "data-sqrl-text-done" => t[:done], "data-sqrl-text-expired" => t[:expired]
+        }
+        attrs["data-sqrl-refresh"] = refresh_url if refresh_url
+        attrs.merge!(extra_attrs.transform_keys(&:to_s))
+        html = "<div#{attributes(attrs)}>\n"
+        html << %(  <a class="#{h(css_class)}__link" data-sqrl-link href="#{h(url)}" rel="nofollow">#{h(link_text)}</a>\n)
+        html << %(  <div class="#{h(css_class)}__qr" data-sqrl-qr>#{QR.svg(url, **qr_options)}</div>\n) if qr
+        html << %(  <p class="#{h(css_class)}__message" data-sqrl-message aria-live="polite">#{h(t[:message])}</p>\n)
+        if refresh_url
+          html << %(  <button type="button" class="#{h(css_class)}__refresh" data-sqrl-refresh-button hidden>#{h(t[:refresh])}</button>\n)
+        end
+        html << %(  <a class="#{h(css_class)}__cancel" href="#{h(cancel_url)}">#{h(cancel_text)}</a>\n) if cancel_url
+        html << "</div>"
+        html << "\n" << script_tag(src: script_url) if script_url
+        html
+      end
+
+      # The markup shown instead of the login block when issuing a login URL was refused
+      # (for example by a rate-limit hook).
+      def unavailable(message: DEFAULT_TEXTS[:unavailable], css_class: "sqrl-login")
+        %(<div class="#{h(css_class)} #{h(css_class)}--unavailable" data-sqrl-unavailable role="status">) \
+          "#{h(message)}</div>"
+      end
+
+      # A script tag for +sqrl.js+: external when +src+ is given, inline otherwise.
+      def script_tag(src: nil)
+        if src
+          %(<script src="#{h(src)}" defer></script>)
+        else
+          "<script>\n#{Assets.javascript}\n</script>"
+        end
+      end
+
+      # Attribute names are escaped too; a name with characters outside the HTML attribute
+      # name grammar is dropped rather than rendered.
+      def attributes(hash)
+        hash.map do |k, v|
+          name = k.to_s
+          next "" unless name.match?(/\A[A-Za-z_:][-A-Za-z0-9_:.]*\z/)
+
+          v.to_s.empty? && name.start_with?("data-") ? " #{name}" : %( #{name}="#{h(v)}")
+        end.join
+      end
+      private_class_method :attributes
+
+      def h(str)
+        CGI.escapeHTML(str.to_s)
+      end
+      private_class_method :h
+    end
+  end
+end