sqrl-core 0.1.0

data/lib/sqrl/protocol.rb

@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+module SQRL
+  # The SQRL client <-> server wire protocol: shared types and parsing.
+  #
+  # A transaction is a sequence of HTTPS POSTs. Every POST body is
+  # +client=<b64u>&server=<b64u>&ids=<b64u>[&pids=<b64u>][&urs=<b64u>]+ where
+  #
+  # * +client+ is a CRLF-separated list of +name=value+ pairs (+ver+, +cmd+, +idk+, ...),
+  # * +server+ is, for the first request, the complete +sqrl://+ URL as received, and for
+  #   every following request the server's previous response *verbatim*,
+  # * +ids+ is the Ed25519 signature (per-site identity key) over the concatenation of the
+  #   +client+ and +server+ base64url strings; +pids+ the same with a previous identity key;
+  #   +urs+ the same with the Unlock Request Signing Key.
+  #
+  # The server answers with a base64url-encoded CRLF list containing at least +ver+, +nut+,
+  # +tif+ (hex transaction information flags) and +qry+ (the path to POST the next request
+  # to).
+  module Protocol
+    # Protocol version this implementation speaks.
+    VERSION = 1
+
+    module_function
+
+    # Parse a CRLF-separated +name=value+ list (LF-only input is tolerated).
+    #
+    # @return [Array<Array(String, String)>] pairs in order
+    def parse_pairs(text)
+      text.to_s.split("\r\n").flat_map { |l| l.split("\n") }.filter_map do |line|
+        next if line.strip.empty?
+
+        k, v = line.split("=", 2)
+        v ? [k.strip, v.chomp("\r")] : [line.strip, ""]
+      end
+    end
+
+    # Whether a +ver=+ value (e.g. +1+, +1,2+, +1-3,5+) includes a given version.
+    def version_supported?(ver, wanted = VERSION)
+      ver.to_s.split(",").any? do |part|
+        part = part.strip
+        if part.include?("-")
+          a, b = part.split("-", 2).map(&:strip)
+          a.match?(/\A\d+\z/) && b.match?(/\A\d+\z/) && a.to_i <= wanted && wanted <= b.to_i
+        else
+          part.match?(/\A\d+\z/) && part.to_i == wanted
+        end
+      end
+    end
+
+    # Decode a base64url text parameter into a UTF-8 string.
+    def decode_text(b64)
+      text = Util.b64u_decode(b64).force_encoding(Encoding::UTF_8)
+      raise FormatError, "text is not UTF-8" unless text.valid_encoding?
+
+      text
+    end
+  end
+
+  # Transaction Information Flags returned by the server. Immutable value object.
+  class Tif
+    # The current identity (+idk+) is known to the server.
+    ID_MATCH = 0x01
+    # The previous identity (+pidk+) is known to the server.
+    PREVIOUS_ID_MATCH = 0x02
+    # The IP of this request matches the IP that requested the nut.
+    IPS_MATCHED = 0x04
+    # The account has SQRL authentication disabled.
+    SQRL_DISABLED = 0x08
+    # The server does not support the requested command / function.
+    FUNCTION_NOT_SUPPORTED = 0x10
+    # Transient error (e.g. stale nut): the client may retry with the new nut.
+    TRANSIENT_ERROR = 0x20
+    # The command could not be executed.
+    COMMAND_FAILED = 0x40
+    # The request was malformed or failed verification.
+    CLIENT_FAILURE = 0x80
+    # The identity does not match the one that started this transaction.
+    BAD_ID_ASSOCIATION = 0x100
+    # The identity has been superseded by a newer (re-keyed) identity.
+    IDENTITY_SUPERSEDED = 0x200
+    # Every bit defined by protocol version 1. "All SQRL clients MUST immediately terminate
+    # any connection and abort any authentication operation with any SQRL server which
+    # includes TIF bits not defined" (On The Wire, tif).
+    DEFINED_BITS = 0x3FF
+    # Every TIF bit that means the command did not succeed.
+    ERROR_BITS = FUNCTION_NOT_SUPPORTED | TRANSIENT_ERROR | COMMAND_FAILED | CLIENT_FAILURE |
+                 BAD_ID_ASSOCIATION | IDENTITY_SUPERSEDED
+
+    attr_reader :value
+
+    def initialize(value = 0)
+      @value = Integer(value)
+      freeze
+    end
+
+    # Parse the hexadecimal +tif=+ value.
+    #
+    # @raise [FormatError]
+    def self.parse(hex)
+      str = hex.to_s.strip
+      raise FormatError, "invalid tif '#{hex}'" unless str.match?(/\A[0-9a-fA-F]+\z/)
+
+      new(str.hex)
+    end
+
+    # @return [Tif] +value+ wrapped (a Tif is returned unchanged)
+    def self.[](value)
+      value.is_a?(Tif) ? value : new(value)
+    end
+
+    # Whether only version-1 bits are set.
+    def defined?
+      @value.nobits?(~DEFINED_BITS)
+    end
+
+    # Test one or more flags.
+    def has?(flag)
+      @value.anybits?(flag)
+    end
+
+    def id_match? = has?(ID_MATCH)
+    def previous_id_match? = has?(PREVIOUS_ID_MATCH)
+    def ips_matched? = has?(IPS_MATCHED)
+    def sqrl_disabled? = has?(SQRL_DISABLED)
+    def function_not_supported? = has?(FUNCTION_NOT_SUPPORTED)
+    def transient_error? = has?(TRANSIENT_ERROR)
+    def command_failed? = has?(COMMAND_FAILED)
+    def client_failure? = has?(CLIENT_FAILURE)
+    def bad_id_association? = has?(BAD_ID_ASSOCIATION)
+    def identity_superseded? = has?(IDENTITY_SUPERSEDED)
+
+    # Any of the error flags.
+    def error?
+      has?(ERROR_BITS)
+    end
+
+    # Lower-case hex as sent on the wire.
+    def to_hex
+      @value.to_s(16)
+    end
+
+    # @return [Tif] bitwise OR with another Tif or Integer
+    def |(other)
+      Tif.new(@value | Tif[other].value)
+    end
+
+    # @return [Tif] bitwise AND with another Tif or Integer
+    def &(other)
+      Tif.new(@value & Tif[other].value)
+    end
+
+    # Clear the given bits.
+    def without(flag)
+      Tif.new(@value & ~flag)
+    end
+
+    # @return [Integer] the raw flag bits
+    def to_i
+      @value
+    end
+
+    # @return [Boolean] whether +other+ carries the same values
+    def ==(other)
+      other.is_a?(Tif) ? other.value == @value : other == @value
+    end
+    alias eql? ==
+
+    # @return [Integer] hash consistent with {#==}
+    def hash
+      @value.hash
+    end
+
+    # @return [String] a short description with secret material redacted
+    def inspect
+      "#<SQRL::Tif 0x#{to_hex}>"
+    end
+    alias to_s to_hex
+  end
+
+  # Client commands.
+  module Command
+    # Ask whether the server knows this identity.
+    QUERY = :query
+    # Authenticate: log in, create the account or re-key it.
+    IDENT = :ident
+    # Disable SQRL authentication for the account.
+    DISABLE = :disable
+    # Re-enable SQRL authentication (needs +urs+).
+    ENABLE = :enable
+    # Remove the SQRL association (needs +urs+).
+    REMOVE = :remove
+    # Every command, in wire order.
+    ALL = [QUERY, IDENT, DISABLE, ENABLE, REMOVE].freeze
+
+    module_function
+
+    # Parse the wire name; returns nil for anything unknown.
+    def parse(str)
+      sym = str.to_s.to_sym
+      ALL.include?(sym) ? sym : nil
+    end
+
+    # The wire name.
+    def to_wire(command)
+      raise ArgumentError, "unknown command #{command.inspect}" unless ALL.include?(command)
+
+      command.to_s
+    end
+  end
+
+  # Client +opt=+ flags.
+  class ClientOptions
+    # The +opt=+ flags, in wire order.
+    FLAGS = %i[sqrlonly hardlock cps suk noiptest].freeze
+
+    # Request that the site disable all non-SQRL authentication.
+    attr_accessor :sqrlonly
+    # Request that the site disable all non-SQRL account recovery.
+    attr_accessor :hardlock
+    # The client can perform Client Provided Session redirection (+url=+ expected).
+    attr_accessor :cps
+    # Ask the server to return the account's SUK (needed before enable/remove).
+    attr_accessor :suk
+    # Do not require the request IP to match the nut's IP.
+    attr_accessor :noiptest
+
+    def initialize(sqrlonly: false, hardlock: false, cps: false, suk: false, noiptest: false)
+      @sqrlonly = sqrlonly
+      @hardlock = hardlock
+      @cps = cps
+      @suk = suk
+      @noiptest = noiptest
+    end
+
+    alias sqrlonly? sqrlonly
+    alias hardlock? hardlock
+    alias cps? cps
+    alias suk? suk
+    alias noiptest? noiptest
+
+    # Parse an +opt=+ value.
+    def self.from_wire(str)
+      o = new
+      str.to_s.split("~").each do |part|
+        flag = part.strip
+        o.public_send("#{flag}=", true) if FLAGS.include?(flag.to_sym)
+      end
+      o
+    end
+
+    # Render the +opt=+ value (+~+ separated), or nil when no option is set.
+    def to_wire
+      set = FLAGS.select { |f| public_send(f) }
+      set.empty? ? nil : set.join("~")
+    end
+
+    # @return [self.class] an unfrozen copy
+    def dup
+      ClientOptions.new(**to_h)
+    end
+
+    # @return [Hash] the values as a plain Hash
+    def to_h
+      FLAGS.to_h { |f| [f, public_send(f) ? true : false] }
+    end
+
+    # @return [Boolean] whether +other+ carries the same values
+    def ==(other)
+      other.is_a?(ClientOptions) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    # @return [Integer] hash consistent with {#==}
+    def hash
+      to_h.hash
+    end
+
+    # @return [String] a short description with secret material redacted
+    def inspect
+      "#<SQRL::ClientOptions #{to_wire || "(none)"}>"
+    end
+  end
+
+  # One button of a server +ask=+.
+  AskButton = Struct.new(:label, :url, keyword_init: true) do
+    def initialize(label:, url: nil)
+      super
+    end
+  end
+
+  # A server question (+ask=<msg>~<button1>[;url]~<button2>[;url]+, each part base64url).
+  class Ask
+    # The question text.
+    attr_reader :message
+    # Zero, one or two buttons. A client shows "OK" when there are none.
+    attr_reader :buttons
+    # Button numbers (1 or 2; 0 is the plain "OK" of a buttonless ask) whose answer lets
+    # the transaction proceed, or nil to accept any answer. A server-side setting only:
+    # it is not part of the wire form.
+    attr_reader :accept
+
+    def initialize(message:, buttons: [], accept: nil)
+      @message = message.to_s
+      @buttons = buttons.map { |b| b.is_a?(AskButton) ? b : AskButton.new(**b) }.freeze
+      @accept = accept.nil? ? nil : Array(accept).map(&:to_i).freeze
+      freeze
+    end
+
+    # Whether a +btn=+ answer lets the login proceed. Any answer does when +accept+ is nil.
+    def accepts?(btn)
+      return true if @accept.nil?
+
+      @accept.include?(btn.to_i)
+    end
+
+    # Parse the wire form.
+    #
+    # @raise [FormatError]
+    def self.parse(value)
+      parts = value.to_s.split("~", -1)
+      message = Protocol.decode_text(parts.shift || "")
+      buttons = parts.first(2).map do |p|
+        label_b64, url = p.split(";", 2)
+        AskButton.new(label: Protocol.decode_text(label_b64 || ""), url: url)
+      end
+      new(message: message, buttons: buttons)
+    end
+
+    # Render the wire form.
+    def to_wire
+      s = Util.b64u_encode(@message.b)
+      @buttons.each do |b|
+        s += "~#{Util.b64u_encode(b.label.to_s.b)}"
+        s += ";#{b.url}" if b.url
+      end
+      s
+    end
+    # @return [Boolean] whether +other+ carries the same values
+
+    def ==(other)
+      other.is_a?(Ask) && other.message == @message && other.buttons == @buttons && other.accept == @accept
+    end
+    alias eql? ==
+    # @return [Integer] hash consistent with {#==}
+
+    def hash
+      [@message, @buttons, @accept].hash
+    end
+  end
+
+  # A parsed server response.
+  class ServerResponse
+    # The response exactly as received (whitespace removed): what the next request's
+    # +server=+ parameter carries.
+    attr_reader :raw
+    # All +name=value+ pairs in order.
+    attr_reader :params
+    attr_reader :ver, :nut, :tif, :qry, :url, :sin, :suk, :ask, :can
+
+    # Parse a base64url response body.
+    #
+    # @raise [ProtocolError, FormatError]
+    def self.parse(body)
+      new(body)
+    end
+
+    def initialize(body)
+      @raw = body.to_s.delete(" \t\r\n\f\v")
+      raise ProtocolError, "empty server response" if @raw.empty?
+
+      decoded = Util.b64u_decode(@raw).force_encoding(Encoding::UTF_8)
+      raise ProtocolError, "server response is not UTF-8" unless decoded.valid_encoding?
+
+      @params = Protocol.parse_pairs(decoded).freeze
+      @ver = fetch("ver") or raise ProtocolError, "response lacks ver"
+      unless Protocol.version_supported?(@ver, Protocol::VERSION)
+        raise ProtocolError, "server speaks version #{@ver}, not #{Protocol::VERSION}"
+      end
+
+      @nut = fetch("nut") or raise ProtocolError, "response lacks nut"
+      raise ProtocolError, "response has an empty nut" if @nut.empty?
+
+      @tif = Tif.parse(fetch("tif") || raise(ProtocolError, "response lacks tif"))
+      unless @tif.defined?
+        raise ProtocolError, "server returned undefined TIF bits (#{@tif.to_hex}); aborting"
+      end
+
+      @qry = fetch("qry") or raise ProtocolError, "response lacks qry"
+      suk = fetch("suk")
+      @suk = suk && !suk.empty? ? Util.b64u_decode_fixed(suk, 32) : nil
+      ask = fetch("ask")
+      @ask = ask && !ask.empty? ? Ask.parse(ask) : nil
+      @url = presence(fetch("url"))
+      @sin = presence(fetch("sin"))
+      @can = presence(fetch("can"))
+      freeze
+    end
+
+    # Value of an arbitrary parameter, or nil.
+    def [](name)
+      fetch(name.to_s)
+      # @return [Boolean] whether +other+ carries the same values
+    end
+
+    # @return [Boolean] whether +other+ carries the same values
+    def ==(other)
+      other.is_a?(ServerResponse) && other.raw == @raw
+    end
+    # @return [Integer] hash consistent with {#==}
+    alias eql? ==
+
+    # @return [Integer] hash consistent with {#==}
+    def hash
+      @raw.hash
+    end
+    # @return [String] a short description with secret material redacted
+
+    def inspect
+      "#<SQRL::ServerResponse tif=0x#{@tif.to_hex} nut=#{@nut} qry=#{@qry}>"
+    end
+
+    private
+
+    def fetch(name)
+      pair = @params.find { |(k, _)| k == name }
+      pair && pair[1]
+    end
+
+    def presence(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+end

data/lib/sqrl/server/config.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Server
+    # Configuration of a {Handler}.
+    #
+    #   config = SQRL::Server::Config.new(host: "example.com") do |c|
+    #     c.on_unknown_identity = :link
+    #     c.ask = SQRL::Ask.new(message: "Log in to Example?", buttons: [{ label: "Yes" }, { label: "No" }])
+    #   end
+    class Config
+      # Accepted values of +on_unknown_identity+.
+      UNKNOWN_IDENTITY_POLICIES = %i[create link refuse].freeze
+      # URL schemes a server can issue: +sqrl+ (HTTPS) or, in testing mode only, +qrl+.
+      SCHEMES = %w[sqrl qrl].freeze
+
+      # Host (with optional port) placed in issued +sqrl://+ URLs. Must be the public host.
+      attr_accessor :host
+      # Path of the SQRL endpoint, also used in +qry=+.
+      attr_accessor :path
+      # Path of the CPS callback used by the default +cps_url+ builder.
+      attr_accessor :callback_path
+      # The URL scheme issued: always +sqrl+ (which means HTTPS) unless +insecure_http+ is
+      # set, in which case it is +qrl+. Read-only; set +insecure_http+ instead.
+      attr_reader :scheme
+      # Loopback-only testing mode: issue +qrl://+ (plain http) URLs. +qrl://+ is not part
+      # of the final SQRL specification and real SQRL clients do not accept it; it exists
+      # so a site can be exercised against the browser extension's test server without
+      # TLS. Validation refuses it for any host that is not loopback.
+      attr_accessor :insecure_http
+      # +x=N+ path extension to scope identities to a path prefix (nil for none).
+      attr_accessor :path_extension
+      # Lifetime in seconds of nuts (login page and per-response).
+      attr_accessor :nut_ttl
+      # Lifetime in seconds of the one-time CPS landing token.
+      attr_accessor :cps_token_ttl
+      # Enforce +IPS_MATCHED+ unless the client sends +noiptest+.
+      attr_accessor :require_ip_match
+      # {Ask} to pose in query replies, or a callable +(context) -> Ask or nil+.
+      attr_accessor :ask
+      # Secret index challenge (+sin=+): a String, or a callable +(context) -> String or nil+.
+      attr_accessor :sin
+      # +:create+ (auto account), +:link+ (needs a pending login with +link_user_ref+) or
+      # +:refuse+.
+      attr_accessor :on_unknown_identity
+      # Callable +(identity, pending_login, command)+ invoked after a successful +ident+ or
+      # +enable+.
+      attr_accessor :on_authenticated
+      # Callable +(token, pending_login) -> String+ building the CPS +url=+.
+      attr_accessor :cps_url
+      # Callable returning the current Time (injectable for tests).
+      attr_accessor :clock
+      # Logger (anything responding to +debug+/+info+/+warn+), or nil.
+      attr_accessor :logger
+      # Hosts (Strings, compared case-insensitively with or without port, or Regexps)
+      # that an integration deriving +host+ from the request may use; nil allows any.
+      attr_accessor :allowed_hosts
+      # Run {Handler#prune!} once every this many issued or handled requests; nil disables.
+      attr_accessor :prune_every
+      # Callable +(context)+ run before a login URL is issued; context has +:ip+ and
+      # +:pending_login_id+. Raise {RateLimited} to refuse.
+      attr_accessor :before_issue
+      # Callable +(context)+ run before a POST is processed (+phase: :request+, with
+      # +:ip+ and +:nut+) and again once the command is known (+phase: :command+, adding
+      # +:command+ and +:idk+). Raise {RateLimited} to refuse.
+      attr_accessor :before_handle
+
+      def initialize(host: nil, path: "/sqrl/cli", callback_path: "/sqrl/callback", scheme: nil, insecure_http: false,
+                     path_extension: nil, nut_ttl: 300, cps_token_ttl: 60, require_ip_match: true,
+                     ask: nil, sin: nil, on_unknown_identity: :create, on_authenticated: nil,
+                     cps_url: nil, clock: nil, logger: nil, allowed_hosts: nil, prune_every: 1000,
+                     before_issue: nil, before_handle: nil)
+        @allowed_hosts = allowed_hosts
+        @prune_every = prune_every
+        @before_issue = before_issue
+        @before_handle = before_handle
+        @host = host
+        @path = path
+        @callback_path = callback_path
+        @insecure_http = insecure_http ? true : false
+        @insecure_http = true if scheme.to_s == "qrl"
+        @scheme = @insecure_http ? "qrl" : (scheme || "sqrl").to_s
+        @path_extension = path_extension
+        @nut_ttl = nut_ttl
+        @cps_token_ttl = cps_token_ttl
+        @require_ip_match = require_ip_match
+        @ask = ask
+        @sin = sin
+        @on_unknown_identity = on_unknown_identity
+        @on_authenticated = on_authenticated
+        @cps_url = cps_url
+        @clock = clock || -> { Time.now }
+        @logger = logger
+        yield self if block_given?
+        validate!
+      end
+
+      # Raise ArgumentError when a value is unusable.
+      def validate!
+        raise ArgumentError, "host is required" if @host.nil? || @host.to_s.strip.empty?
+        raise ArgumentError, "host must not contain a scheme or path" if @host.match?(%r{://|/})
+        raise ArgumentError, "path must start with /" unless @path.to_s.start_with?("/")
+        raise ArgumentError, "callback_path must start with /" unless @callback_path.to_s.start_with?("/")
+        raise ArgumentError, "scheme must be sqrl or qrl" unless SCHEMES.include?(@scheme)
+        if insecure_http? && !URL.loopback?(bare_host)
+          raise ArgumentError, "insecure_http (plain http, qrl://) is only allowed for loopback hosts, not #{bare_host}"
+        end
+
+        warn_insecure_once if insecure_http?
+        unless @path_extension.nil? || (@path_extension.is_a?(Integer) && @path_extension.positive?)
+          raise ArgumentError, "path_extension must be nil or a positive Integer"
+        end
+        raise ArgumentError, "nut_ttl must be a positive number" unless positive_number?(@nut_ttl)
+        raise ArgumentError, "cps_token_ttl must be a positive number" unless positive_number?(@cps_token_ttl)
+        unless UNKNOWN_IDENTITY_POLICIES.include?(@on_unknown_identity)
+          raise ArgumentError, "on_unknown_identity must be one of #{UNKNOWN_IDENTITY_POLICIES.join(", ")}"
+        end
+        raise ArgumentError, "ask must be an SQRL::Ask or a callable" unless valid_ask?
+        raise ArgumentError, "sin must be a String or a callable" unless valid_sin?
+        unless @on_authenticated.nil? || callable?(@on_authenticated)
+          raise ArgumentError,
+                "on_authenticated must be callable"
+        end
+        raise ArgumentError, "cps_url must be callable" unless @cps_url.nil? || callable?(@cps_url)
+        raise ArgumentError, "clock must be callable" unless callable?(@clock)
+        unless @allowed_hosts.nil? || (@allowed_hosts.is_a?(Array) && @allowed_hosts.all? do |h|
+          h.is_a?(String) || h.is_a?(Regexp)
+        end)
+          raise ArgumentError, "allowed_hosts must be nil or an Array of Strings and Regexps"
+        end
+        unless @prune_every.nil? || (@prune_every.is_a?(Integer) && @prune_every.positive?)
+          raise ArgumentError, "prune_every must be nil or a positive Integer"
+        end
+        raise ArgumentError, "before_issue must be callable" unless @before_issue.nil? || callable?(@before_issue)
+        raise ArgumentError, "before_handle must be callable" unless @before_handle.nil? || callable?(@before_handle)
+
+        true
+      end
+
+      # The host without port (IPv6 literals keep their brackets), lower-cased.
+      def bare_host
+        host, = URL.split_host_port(@host.to_s)
+        host.to_s.downcase
+      rescue FormatError
+        @host.to_s.downcase
+      end
+
+      # Whether +host+ (with or without port) is acceptable under +allowed_hosts+. Always
+      # true when no list is configured.
+      def host_allowed?(host)
+        return true if @allowed_hosts.nil?
+
+        candidate = host.to_s.downcase
+        bare = begin
+          URL.split_host_port(candidate).first.to_s
+        rescue FormatError
+          candidate
+        end
+        @allowed_hosts.any? do |allowed|
+          if allowed.is_a?(Regexp)
+            candidate.match?(allowed) || bare.match?(allowed)
+          else
+            a = allowed.downcase
+            a == candidate || a == bare
+          end
+        end
+      end
+
+      # +https+ (or +http+ in +insecure_http+ mode).
+      def http_scheme
+        insecure_http? ? "http" : "https"
+      end
+
+      # Whether the site issues +qrl://+ (plain http) URLs; see +insecure_http+.
+      def insecure_http? = @insecure_http ? true : false
+
+      # Warning logged once when +insecure_http+ is enabled.
+      INSECURE_WARNING = "[sqrl] insecure_http is a loopback-only testing mode; real SQRL clients require " \
+                         "sqrl:// over HTTPS"
+      @insecure_warned = false
+      @insecure_warning_mutex = Mutex.new
+
+      class << self
+        # Reset the one-time insecure_http warning (tests).
+        def reset_warnings!
+          @insecure_warning_mutex.synchronize { @insecure_warned = false }
+        end
+
+        # Log {INSECURE_WARNING} once per process.
+        # @api private
+        def warn_insecure_once(logger)
+          @insecure_warning_mutex.synchronize do
+            return if @insecure_warned
+
+            @insecure_warned = true
+          end
+          logger.respond_to?(:warn) ? logger.warn(INSECURE_WARNING) : Kernel.warn(INSECURE_WARNING)
+        end
+      end
+
+      # +https://host+
+      def origin
+        "#{http_scheme}://#{@host}"
+      end
+
+      # @return [Time] the configured clock's current time
+      def now
+        @clock.call
+      end
+
+      # Resolve the +ask+ setting for a request context.
+      def ask_for(context)
+        callable?(@ask) ? @ask.call(context) : @ask
+      end
+
+      # Resolve the +sin+ setting for a request context.
+      def sin_for(context)
+        value = callable?(@sin) ? @sin.call(context) : @sin
+        value&.to_s
+      end
+
+      # Build the CPS +url=+ for a token.
+      def cps_url_for(token, pending_login)
+        return @cps_url.call(token, pending_login) if @cps_url
+
+        "#{origin}#{@callback_path}?t=#{token}"
+      end
+
+      def require_ip_match? = @require_ip_match ? true : false
+
+      private
+
+      # @return [void] see {Config.warn_insecure_once}
+      def warn_insecure_once
+        self.class.warn_insecure_once(@logger)
+      end
+
+      def positive_number?(v)
+        v.is_a?(Numeric) && v.positive?
+      end
+
+      def callable?(v)
+        v.respond_to?(:call)
+      end
+
+      def valid_ask?
+        @ask.nil? || @ask.is_a?(Ask) || callable?(@ask)
+      end
+
+      def valid_sin?
+        @sin.nil? || @sin.is_a?(String) || callable?(@sin)
+      end
+    end
+  end
+end