sqrl-core 0.1.0

data/lib/sqrl/test_vectors.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SQRL
+  # Test vectors published by GRC and by the SQRL developer community, shared by every
+  # gem's test-suite.
+  #
+  # Sources:
+  # * "SQRL Cryptography" v1.04 (December 2019), "SQRL Cryptography Test Vectors": the
+  #   Spec-Vectors-Identity (password, rescue code, textual identity) and the client-side
+  #   SQRL-PASS.log / SQRL.log excerpts.
+  # * https://www.grc.com/sqrl/storage.htm: the official EnScrypt vectors.
+  # * grc.sqrl.dev newsgroup, "SQRL Identity encryption" (Adam Comley, 2014): EnScrypt with
+  #   a 16-byte salt, cross-validated against GRC's EnScrypt.exe.
+  # * grc.sqrl newsgroup, "Base56 Examples" (Paul Holder, March 2019): base56 textual
+  #   encodings validated against the GRC SQRL client's export.
+  # * The open-source Android SQRL client's test code: a complete S4 identity file.
+  module TestVectors
+    # Password of GRC's Spec-Vectors-Identity.
+    SPEC_PASSWORD = "Zingo-Bingo-Slingo-Dingo"
+    # Rescue code of the Spec-Vectors-Identity.
+    SPEC_RESCUE_CODE = "1198-8748-7132-2838-8318-7570"
+    # The Spec-Vectors-Identity as a textual (base56) identity.
+    SPEC_TEXTUAL = <<~TEXT.chomp
+      KKcC 3BaX akxc Xwbf xki7
+      k7mF GHhg jQes gzWd 6TrK
+      vMsZ dBtB pZbC zsz8 cUWj
+      DtS2 ZK2s ZdAQ 8Yx3 iDyt
+      QuXt CkTC y6gc qG8n Xfj9
+      bHDA 422
+    TEXT
+    # Identity Master Key of the Spec-Vectors-Identity (hex).
+    SPEC_IMK = "2E471E106D758F3C7B242C8A4A0513A7192D8EDDB917BDD019F19E38ED292BA8"
+    # Per-site values for sqrl.grc.com from SQRL.log.
+    SPEC_SITE = "sqrl.grc.com"
+    # Per-site Ed25519 seed for sqrl.grc.com (hex).
+    SPEC_SITE_SEED = "7A550E0797EF9E617D0E544EBE27FDE749D9EC2472BF9618DEE4C063EEFD51B5"
+    # Per-site public key for sqrl.grc.com (hex).
+    SPEC_SITE_PUBLIC_KEY = "DA3801F9C47E1279588253DD193A0EB9C29823A083EAC52A7F893D32D92E897B"
+    # idk= (base64url) for sqrl.grc.com.
+    SPEC_SITE_IDK = "2jgB-cR-EnlYglPdGToOucKYI6CD6sUqf4k9MtkuiXs"
+
+    # SQRL.log transaction 1 and 2 (the query and ident against sqrl.grc.com).
+    SPEC_URL = "sqrl://sqrl.grc.com/cli.sqrl?nut=fXkb4MBToCm7&can=aHR0cHM6Ly9zcXJsLmdyYy5jb20vZGVtbw"
+    # The can= cancel URL from SQRL.log.
+    SPEC_CANCEL_URL = "https://sqrl.grc.com/demo"
+    # Decoded client= of the query request in SQRL.log.
+    SPEC_QUERY_CLIENT = "ver=1\r\ncmd=query\r\nidk=#{SPEC_SITE_IDK}\r\nopt=cps~suk\r\n".freeze
+    # Start of the base64url client= of the query request.
+    SPEC_QUERY_CLIENT_B64_PREFIX = "client=dmVyPTENCmNtZD1xdWVyeQ0KaWRrPTJqZ0ItY1ItRW5sWWdsUGRHVG9PdWNLWUk2Q0Q2c1VxZjRrOU10a3Vp"
+    # Fragment of the base64url server= of the query request.
+    SPEC_QUERY_SERVER_B64_FRAGMENT = "&server=c3FybDovL3NxcmwuZ3JjLmNvbS9jbGkuc3FybD9udXQ9ZlhrYjRNQlRvQ203JmNhbj1hSFIwY0hNNkx5OXpj"
+    # ids= signature of the query request (base64url).
+    SPEC_QUERY_IDS = "qXFikmg_jZQJ7GjKCA_zBwzras2QyQAwWw2s80ZcUHmLLBUN5_hPuFtB6ZoV5wUcNs5XmSrqg1FQwGA6RlVBAQ"
+    # Decoded first server reply from SQRL.log.
+    SPEC_REPLY1 = "ver=1\r\nnut=1WM9lfF1ST-z\r\ntif=5\r\nqry=/cli.sqrl?nut=1WM9lfF1ST-z\r\n" \
+                  "suk=BMFDm7bPlsQojuJsoDTvlS1McnwgScvktF84vLjscGk\r\n"
+    # Start of the base64url first reply.
+    SPEC_REPLY1_B64_PREFIX = "dmVyPTENCm51dD0xV005bGZGMVNULXoNCnRpZj01DQpxcnk9L2NsaS5zcXJsP251dD0xV005bGZGMVNULXoN"
+    # suk= carried by the first reply.
+    SPEC_REPLY1_SUK = "BMFDm7bPlsQojuJsoDTvlS1McnwgScvktF84vLjscGk"
+    # POST URL of the ident request.
+    SPEC_IDENT_URL = "https://sqrl.grc.com/cli.sqrl?nut=1WM9lfF1ST-z"
+    # Decoded client= of the ident request in SQRL.log.
+    SPEC_IDENT_CLIENT = "ver=1\r\ncmd=ident\r\nidk=#{SPEC_SITE_IDK}\r\nopt=cps~suk\r\n".freeze
+    # Start of the base64url client= of the ident request.
+    SPEC_IDENT_CLIENT_B64_PREFIX = "client=dmVyPTENCmNtZD1pZGVudA0KaWRrPTJqZ0ItY1ItRW5sWWdsUGRHVG9PdWNLWUk2Q0Q2c1VxZjRrOU10a3Vp"
+    # ids= signature of the ident request (base64url).
+    SPEC_IDENT_IDS = "kQI05IpE_cu4u0mf7jymbap09hmS6ZCWjBGKUYnSNVRTXPbreTvDWHKNbSkUlQT2bx3wXwW3cCLBD0Qedd64AA"
+    # Decoded second server reply from SQRL.log.
+    SPEC_REPLY2 = "ver=1\r\nnut=BEFAI1tJYfBm\r\ntif=5\r\nqry=/cli.sqrl?nut=BEFAI1tJYfBm\r\n" \
+                  "suk=BMFDm7bPlsQojuJsoDTvlS1McnwgScvktF84vLjscGk\r\n" \
+                  "url=https://sqrl.grc.com/auth.test?4hVTe9LGHhMTuxz_mm6vRc_q\r\n"
+    # The CPS url= from SQRL.log.
+    SPEC_CPS_URL = "https://sqrl.grc.com/auth.test?4hVTe9LGHhMTuxz_mm6vRc_q"
+
+    # EnScrypt vectors: [password, salt hex, iterations, expected hex].
+    ENSCRYPT = [
+      # Official vectors from https://www.grc.com/sqrl/storage.htm
+      ["", "", 1, "a8ea62a6e1bfd20e4275011595307aa302645c1801600ef5cd79bf9d884d911c"],
+      ["", "", 100, "45a42a01709a0012a37b7b6874cf16623543409d19e7740ed96741d2e99aab67"],
+      ["password", "", 123, "129d96d1e735618517259416a605be7094c2856a53c14ef7d4e4ba8e4ea36aeb"],
+      ["password", "0000000000000000000000000000000000000000000000000000000000000000", 123,
+       "2f30b9d4e5c48056177ff90a6cc9da04b648a7e8451dfa60da56c148187f6a7d"],
+      # SQRL-PASS.log: password DeScryption, 179 iterations
+      [SPEC_PASSWORD, "F5019F96E9F64D32BEAE43145ACEF2CF", 179,
+       "bc151224fc6b72152021edbe3ade523f98be99c491334bba9fd8b587eb51e36d"],
+      # SQRL-PASS.log: QuickPass hint "Zing", 31 iterations
+      ["Zing", "CD2E1EA56DE20FE036B6D2FA867DF50A", 31,
+       "ddc7f5d12caa26a869488ad83df8ed480072076dfd94eee5f6f1bd0dde02b9d9"],
+      # grc.sqrl.dev newsgroup, 16- and 32-byte salts
+      ["Sqrl123Test", "0123456789abcdef0123456789abcdef", 63,
+       "83961678d0e808f29b5dcc045236ad7fd249d7dfd7284b461976b1f1b8a45df0"],
+      ["Sqrl123Test", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 63,
+       "da06576fbe58fb20bd8c4f1204a87aa8fad21078473dd770bb7ee7faff8a2f4a"]
+    ].map(&:freeze).freeze
+
+    # Base56 vectors validated against GRC's client: {hex input => raw encoding}.
+    BASE56_SHORT = {
+      "00" => "22Y", "01" => "32B", "0F" => "H2M", "55" => "X3v", "C5" => "X57", "FE" => "Y6e", "FF" => "Z6V",
+      "0000" => "222B", "0101" => "b628", "0F0F" => "rE3N", "1010" => "SK3T", "7F7F" => "rQCj",
+      "8080" => "SVC5", "FEFE" => "gpN7", "FFFF" => "HuNh",
+      "000000" => "22222z", "010101" => "tyN22r", "7F7F7F" => "9Tar2S", "808080" => "2Sxr2D",
+      "FEFEFE" => "GuAh3n", "FFFFFF" => "9tXh3W",
+      "0102030405060708090A0B0C0D0E0F10" => "tG5vDbjTXT2zfJ5cMfvg3A62d"
+    }.freeze
+    # Base56 example: 80 random bytes (hex).
+    BASE56_80_HEX = "0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627" \
+                    "28292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F50"
+    # Base56 example: the 80 bytes as GRC's client exports them.
+    BASE56_80_TEXT = <<~TEXT.chomp
+      b6w8 RYMv S427 Gtt5 sXBj
+      UB5n vHZH PbHr uAM9 MgUR
+      fzT8 qs8f EEEp kUPV GH6R
+      ac4u Zdrk CwLJ Wxmy 8upX
+      rU9N Bn6P qcY9 HXKt ybEC
+      Sdh9 R22r SjAd 48i2 Y
+    TEXT
+    # Base56 example: 87 random bytes (hex).
+    BASE56_87_HEX = "18A2D975F61A3B6F1975FA2A9E3FBA2C7BE73732A0E34F006328E4BD938CFB6E292A50845C5A6B83F769" \
+                    "7EAC8A49BF97221C2F06C1F4B251BDB865AF1E1E28E62D635959BEF7927CD658A7C2CA1AD5570DC6C066BA6EAF"
+    # Base56 example: the 87 bytes as GRC's client exports them.
+    BASE56_87_TEXT = <<~TEXT.chomp
+      sMrK xrbJ dHz5 s3mu EGWw
+      RjWM UbAV MMsq SwMM R7C6
+      theF MsSg PDJ4 BHVb jLau
+      KpW8 cbsU mTpd eueZ ZYMU
+      HgcB kffR Nviu pxb9 UvxN
+      fN54 3id9 CdRe L254 ZzEb
+      4LBd pNL
+    TEXT
+    # Sample textual identity (a single type 2 block) from the Android client's test harness.
+    ANDROID_TEXTUAL = "KB3Z 8My9 CVUX C34K B8NM bEXm jcUK RAq6 JT9p DaYW UstG K9hH xX98 KxHU weVa RvpV " \
+                      "wJd5 JXbf eEDf 4cYy hzNL j6dW Ehq3 KXCV YSBf nRJd rAN"
+
+    # A real identity file (from the open-source Android SQRL client's test code) with the
+    # password +Testing1234+ and rescue code +7276-0587-2230-1119-8559-3839+.
+    ANDROID_IDENTITY_HEX = "7371726c646174617d0001002d00b51fd99559b887d106a8d877c70133bb20a12fa1a7c829b194db94f309c5" \
+                           "000000f30104050f000d174cc6e7b70baa158aa4ce75e2f2b99a02a40e4beb2e5d16c2f03442bd3e932035" \
+                           "419a63885a663125a600e5486c42b38f708c1094ced1ab0b0050137f6df449caf78581fec678408a804caf74" \
+                           "f91c490002005528fc85e3e36866a85574146fe7776d09cf0000004a4e12277dd48366fc1f335dd37188bbcb" \
+                           "a02bc32a12aef0188f5e83593665518483d638b80051c2b4b013491eb06835"
+    # Password of the Android client's test identity file.
+    ANDROID_PASSWORD = "Testing1234"
+    # Rescue code of the Android client's test identity file.
+    ANDROID_RESCUE_CODE = "7276-0587-2230-1119-8559-3839"
+
+    # RFC 7748 X25519 base-point vector.
+    X25519_ALICE_PRIVATE = "77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a"
+    # RFC 7748 X25519 test vector: Alice's public key (hex).
+    X25519_ALICE_PUBLIC = "8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a"
+  end
+end

data/lib/sqrl/textual.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SQRL
+  # The base56 "textual identity" format.
+  #
+  # The rescue (type 2) and previous-identity (type 3) blocks are treated as one
+  # little-endian number and written in base56 (digits 2-9, upper-case letters without I
+  # and O, lower-case letters without l and o). After every 19 characters a check
+  # character is inserted: SHA-256(19 chars || line number) interpreted as a little-endian
+  # number, modulo 56. For display the characters are grouped in fours, five groups per line.
+  module Textual
+    # The base56 alphabet.
+    ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnpqrstuvwxyz".b.freeze
+    CHARS_PER_LINE = 19
+    LOG2_56 = 5.807_354_922_057_604
+    INDEX = ALPHABET.each_byte.with_index.to_h.freeze
+    private_constant :CHARS_PER_LINE, :LOG2_56, :INDEX
+
+    module_function
+
+    # Index of a byte in the alphabet, or nil.
+    def alphabet_index(byte)
+      INDEX[byte]
+    end
+
+    # Divide a little-endian big number (Array of bytes) in place by 56; returns the remainder.
+    def divmod56!(num)
+      rem = 0
+      (num.length - 1).downto(0) do |i|
+        cur = (rem << 8) | num[i]
+        num[i] = cur / 56
+        rem = cur % 56
+      end
+      rem
+    end
+
+    # Check character for one line of data characters.
+    def check_char(line_chars, line)
+      digest = Crypto.sha256(line_chars.pack("C*") + [line].pack("C"))
+      rem = 0
+      digest.bytes.reverse_each { |b| rem = ((rem << 8) | b) % 56 }
+      ALPHABET.getbyte(rem)
+    end
+
+    # Encode bytes into the raw textual identity string (check characters included, no spacing).
+    def encode(data)
+      data = data.b
+      expected_len = ((data.bytesize * 8) / LOG2_56).ceil
+      num = data.bytes
+      out = []
+      line_chars = []
+      line = 0
+      expected_len.times do
+        if line_chars.length == CHARS_PER_LINE
+          out << check_char(line_chars, line)
+          line_chars = []
+          line = (line + 1) & 0xFF
+        end
+        c = num.all?(&:zero?) ? ALPHABET.getbyte(0) : ALPHABET.getbyte(divmod56!(num))
+        out << c
+        line_chars << c
+      end
+      out << check_char(line_chars, line)
+      out.pack("C*").force_encoding("UTF-8")
+    end
+
+    # Format a raw textual identity for display: groups of four, five groups per line.
+    def format_for_display(raw)
+      out = +""
+      raw.each_char.with_index do |c, i|
+        if i.positive?
+          if (i % 20).zero?
+            out << "\n"
+          elsif (i % 4).zero?
+            out << " "
+          end
+        end
+        out << c
+      end
+      out
+    end
+
+    # Decode a textual identity (whitespace and dashes are ignored) into the block bytes.
+    # Raises FormatError naming the (1-based) line whose check character failed.
+    def decode(text)
+      cleaned = text.to_s.b.delete(" \t\r\n\f\v-").bytes
+      raise FormatError, "empty textual identity" if cleaned.empty?
+
+      cleaned.each do |c|
+        raise FormatError, "invalid character '#{c.chr}' in textual identity" unless alphabet_index(c)
+      end
+      total = cleaned.length
+      data_chars = []
+      line_chars = []
+      line = 0
+      cleaned.each_with_index do |c, i|
+        is_check = line_chars.length == CHARS_PER_LINE || i == total - 1
+        if is_check
+          raise FormatError, "check character mismatch on line #{line + 1}" unless c == check_char(line_chars, line)
+
+          line_chars = []
+          line = (line + 1) & 0xFF
+        else
+          data_chars << c
+          line_chars << c
+        end
+      end
+      expected_bytes = ((data_chars.length * LOG2_56) / 8.0).floor
+      num = Array.new(expected_bytes + 2, 0)
+      data_chars.reverse_each do |c|
+        carry = alphabet_index(c)
+        num.map! do |byte|
+          cur = (byte * 56) + carry
+          carry = cur >> 8
+          cur & 0xFF
+        end
+        raise FormatError, "textual identity value out of range" unless carry.zero?
+      end
+      raise FormatError, "textual identity value out of range" if num[expected_bytes..].any? { |b| b != 0 }
+
+      num.first(expected_bytes).pack("C*")
+    end
+  end
+end

data/lib/sqrl/url.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module SQRL
+  # A parsed +sqrl://+ URL.
+  #
+  # * The *site key* that all per-site keys are derived from is the lower-cased host name
+  #   (user info and port stripped). When the URL carries an +x=N+ parameter, the first +N+
+  #   characters of the path (including the leading +/+) are appended.
+  # * The *POST URL* is the same URL with the scheme replaced by +https+. +qrl://+, the
+  #   plain-http scheme of GRC's early drafts, is not part of the final specification: it is
+  #   parsed, accepted for loopback hosts only, and refused by {SQRL::Session} unless it was
+  #   created with +insecure: true+ (a testing mode for the browser extension's test server).
+  # * +can=+ carries a base64url-encoded URL to send the browser to if the user cancels.
+  class URL
+    # The URL exactly as received (this is what the first +server=+ parameter carries).
+    attr_reader :original
+    # +sqrl+ (or +qrl+ in the loopback-only testing mode), lower-cased.
+    attr_reader :scheme
+    # +host[:port]+ without user info, as used for the POST URL.
+    attr_reader :authority
+    # Lower-cased host name.
+    attr_reader :host
+    # Explicit port, if any.
+    attr_reader :port
+    # The path (starts with +/+; +/+ if absent).
+    attr_reader :path
+    # The raw query string without the leading +?+.
+    attr_reader :query
+    # The +nut=+ value, if any.
+    attr_reader :nut
+    # Value of +x=+ (path characters included in the site key).
+    attr_reader :path_extension
+    # Decoded +can=+ cancel URL (relative URLs are resolved against the site).
+    attr_reader :cancel_url
+    # Site key string used for key derivation.
+    attr_reader :site_key
+
+    # Hosts for which the plain-http +qrl://+ testing scheme is tolerated at all.
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 [::1]].freeze
+
+    # Parse a +sqrl://+ (or loopback-only +qrl://+) URL.
+    #
+    # @param input [String]
+    # @return [URL]
+    # @raise [FormatError]
+    def self.parse(input)
+      new(input)
+    end
+
+    # Split a query string into +[key, value]+ pairs. Values are percent-decoded only for
+    # the characters SQRL servers may legitimately escape; the +nut+ is otherwise used
+    # verbatim.
+    #
+    # @param query [String]
+    # @return [Array<Array(String, String)>]
+    def self.query_pairs(query)
+      query.to_s.split("&").reject(&:empty?).map do |kv|
+        k, v = kv.split("=", 2)
+        [k, v ? percent_decode(v) : ""]
+      end
+    end
+
+    # Percent-decode a string, leaving malformed escapes untouched.
+    def self.percent_decode(str)
+      return str unless str.include?("%")
+
+      str.gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }
+         .force_encoding(Encoding::UTF_8)
+         .scrub
+    end
+
+    # Whether +host+ (lower-cased, IPv6 literals in brackets) is a loopback address:
+    # +localhost+ and +*.localhost+, +127.0.0.0/8+, +[::1]+ and the IPv4-mapped form of
+    # 127/8. Any other IPv6 literal is not loopback.
+    def self.loopback?(host)
+      h = host.to_s.downcase
+      return true if LOOPBACK_HOSTS.include?(h) || h.end_with?(".localhost")
+      return true if h.match?(/\A127\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/)
+
+      bare = h.delete_prefix("[").delete_suffix("]")
+      bare == "::1" || bare == "0:0:0:0:0:0:0:1" || bare.match?(/\A::ffff:127\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/)
+    end
+
+    # Split +host[:port]+ handling IPv6 literals. Returns +[host, port_or_nil]+.
+    def self.split_host_port(hostport)
+      if hostport.start_with?("[")
+        close = hostport.index("]")
+        raise FormatError, "unterminated IPv6 literal" unless close
+
+        host = hostport[0..close]
+        after = hostport[(close + 1)..]
+        return [host, nil] if after.empty?
+        raise FormatError, "invalid port" unless after.start_with?(":") && after[1..].match?(/\A\d+\z/)
+
+        return [host, parse_port(after[1..])]
+      end
+      host, port = hostport.rpartition(":").then { |h, sep, p| sep.empty? ? [hostport, nil] : [h, p] }
+      return [host, nil] if port.nil?
+      raise FormatError, "invalid port" unless port.match?(/\A\d+\z/)
+
+      [host, parse_port(port)]
+    end
+
+    def self.parse_port(str)
+      port = Integer(str, 10)
+      raise FormatError, "invalid port" unless port.between?(0, 65_535)
+
+      port
+    end
+
+    def initialize(input)
+      raise FormatError, "not a URL" unless input.is_a?(String)
+
+      @original = input.strip
+      scheme, rest = @original.split("://", 2)
+      raise FormatError, "not a URL" unless rest
+
+      @scheme = scheme.downcase
+      raise FormatError, "unsupported scheme '#{@scheme}'" unless %w[sqrl qrl].include?(@scheme)
+
+      rest = rest.split("#", 2).first || ""
+      end_of_authority = rest.index(%r{[/?]}) || rest.length
+      authority_raw = rest[0...end_of_authority]
+      path_and_query = rest[end_of_authority..] || ""
+      path, query = path_and_query.split("?", 2)
+      @path = path.nil? || path.empty? ? "/" : path
+      @query = query || ""
+
+      hostport = authority_raw.include?("@") ? authority_raw.rpartition("@").last : authority_raw
+      host, @port = self.class.split_host_port(hostport)
+      raise FormatError, "missing host" if host.empty?
+
+      @host = host.downcase
+      raise FormatError, "invalid host" if @host.match?(%r{[\s/\\]})
+
+      @authority = @port ? "#{@host}:#{@port}" : @host
+      if @scheme == "qrl" && !self.class.loopback?(@host)
+        raise FormatError, "plain-http qrl:// URLs are only allowed for localhost"
+      end
+
+      @nut = nil
+      @path_extension = 0
+      cancel = nil
+      self.class.query_pairs(@query).each do |k, v|
+        case k
+        when "nut" then @nut = v
+        when "x", "X"
+          # GRC's client treats x= and X= identically and parses the value with an
+          # "intolerant" converter that stops at the first non-digit.
+          digits = v[/\A\d*/]
+          @path_extension = digits.empty? ? 0 : digits.to_i
+        when "can"
+          bytes = Util.b64u_decode(v)
+          cancel = bytes.force_encoding(Encoding::UTF_8)
+          raise FormatError, "can= is not UTF-8" unless cancel.valid_encoding?
+        end
+      end
+
+      @site_key = @host.dup
+      if @path_extension.positive?
+        take = [@path_extension, @path.bytesize].min
+        # never cut in the middle of a multi-byte character
+        take -= 1 until @path.byteslice(0, take).force_encoding(Encoding::UTF_8).valid_encoding?
+        @site_key << @path.byteslice(0, take).force_encoding(Encoding::UTF_8)
+      end
+      @site_key.freeze
+      @cancel_url = cancel && resolve(cancel)
+      freeze
+    end
+
+    # +https+ (or +http+ for +qrl://+).
+    def http_scheme
+      @scheme == "qrl" ? "http" : "https"
+    end
+
+    # +https://authority+
+    def origin
+      "#{http_scheme}://#{@authority}"
+    end
+
+    # The URL to POST the first (query) request to.
+    def post_url
+      @query.empty? ? "#{origin}#{@path}" : "#{origin}#{@path}?#{@query}"
+    end
+
+    # The URL to POST a follow-up request to, from the server's +qry=+ value.
+    #
+    # +qry+ must be a path on the same host (it starts with +/+); absolute URLs pointing
+    # elsewhere are rejected to stop a compromised response redirecting signatures.
+    #
+    # @raise [ProtocolError]
+    def post_url_for_qry(qry)
+      qry = qry.to_s.strip
+      unless qry.start_with?("/") && !qry.start_with?("//")
+        raise ProtocolError, "qry must be a server-relative path, got '#{qry}'"
+      end
+
+      "#{origin}#{qry}"
+    end
+
+    # Site key bytes, optionally extended with an Alt-ID (+site_key || 0x00 || alt_id+).
+    #
+    # @return [String] binary
+    def site_key_bytes(alt_id = nil)
+      bytes = @site_key.b
+      alt = alt_id.to_s.strip
+      bytes << "\0" << alt.b unless alt.empty?
+      bytes
+    end
+
+    # Resolve a possibly-relative URL (from +can=+ or +url=+) against this site.
+    def resolve(target)
+      t = target.to_s.strip
+      if t.start_with?("https://", "http://")
+        t
+      elsif t.start_with?("/")
+        "#{origin}#{t}"
+      else
+        "#{origin}/#{t}"
+      end
+    end
+
+    # Whether an absolute URL (e.g. the CPS +url=+) points at this site's host, using the
+    # site's own HTTP scheme (https for sqrl://, http only for loopback qrl:// sites), so
+    # a reply cannot downgrade the browser to plain http.
+    def same_host?(target)
+      t = target.to_s.strip
+      scheme, rest = t.split("://", 2)
+      return false unless rest && scheme.casecmp?(http_scheme)
+
+      stop = rest.index(%r{[/?#]}) || rest.length
+      hostport = rest[0...stop]
+      hostport = hostport.rpartition("@").last if hostport.include?("@")
+      host, = self.class.split_host_port(hostport)
+      host.casecmp?(@host)
+    rescue FormatError
+      false
+    end
+
+    # @return [String] the URL as received
+    def to_s
+      @original
+    end
+
+    # @return [Boolean] whether +other+ carries the same values
+    def ==(other)
+      other.is_a?(URL) && other.original == @original
+    end
+    alias eql? ==
+
+    # @return [Integer] hash consistent with {#==}
+    def hash
+      @original.hash
+    end
+
+    # @return [String] a short description with secret material redacted
+    def inspect
+      "#<SQRL::URL #{@original}>"
+    end
+  end
+end

data/lib/sqrl/util.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module SQRL
+  # Small helpers: base64url (no padding), hex, random bytes, little-endian integers,
+  # constant-time comparison and best-effort wiping of secret strings.
+  module Util
+    module_function
+
+    # Encode bytes as base64url without padding (the only base64 variant SQRL uses).
+    def b64u_encode(data)
+      [data].pack("m0").tr("+/", "-_").delete("=")
+    end
+
+    # Decode base64url. Padding characters and ASCII whitespace are tolerated and ignored,
+    # as the SQRL storage spec requires for the textual +SQRLDATA+ form.
+    def b64u_decode(text)
+      raise FormatError, "invalid base64url: not a string" unless text.is_a?(String)
+
+      cleaned = text.delete(" \t\r\n\f\v=")
+      raise FormatError, "invalid base64url: bad characters" unless cleaned.match?(/\A[A-Za-z0-9_-]*\z/)
+      raise FormatError, "invalid base64url: bad length" if (cleaned.length % 4) == 1
+
+      padded = cleaned.tr("-_", "+/")
+      padded += "=" * ((4 - (padded.length % 4)) % 4)
+      padded.unpack1("m0").b
+    rescue ArgumentError => e
+      raise FormatError, "invalid base64url: #{e.message}"
+    end
+
+    # Decode base64url into exactly +size+ bytes.
+    def b64u_decode_fixed(text, size)
+      bytes = b64u_decode(text)
+      raise FormatError, "expected #{size} bytes, got #{bytes.bytesize}" unless bytes.bytesize == size
+
+      bytes
+    end
+
+    # Lower-case hex encoding.
+    def hex_encode(data)
+      data.unpack1("H*")
+    end
+
+    # Hex decoding (case-insensitive, whitespace ignored).
+    def hex_decode(text)
+      cleaned = text.delete(" \t\r\n\f\v")
+      raise FormatError, "odd-length hex string" if cleaned.length.odd?
+      raise FormatError, "bad hex" unless cleaned.match?(/\A[0-9a-fA-F]*\z/)
+
+      [cleaned].pack("H*")
+    end
+
+    # +n+ cryptographically secure random bytes.
+    def random_bytes(n)
+      SecureRandom.random_bytes(n)
+    end
+
+    # Read a little-endian unsigned 16-bit integer.
+    # @param bytes [String]
+    # @param offset [Integer]
+    # @return [Integer]
+    def le_u16(bytes, offset = 0)
+      bytes.byteslice(offset, 2).unpack1("v")
+    end
+
+    # Read a little-endian unsigned 32-bit integer.
+    # @param bytes [String]
+    # @param offset [Integer]
+    # @return [Integer]
+    def le_u32(bytes, offset = 0)
+      bytes.byteslice(offset, 4).unpack1("V")
+    end
+
+    # @return [String] +value+ as 2 little-endian bytes
+    def pack_le_u16(value)
+      [value].pack("v")
+    end
+
+    # @return [String] +value+ as 4 little-endian bytes
+    def pack_le_u32(value)
+      [value].pack("V")
+    end
+
+    # XOR two equal-length byte strings, returning a new binary string.
+    def xor(a, b)
+      raise ArgumentError, "xor length mismatch" unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).map { |x, y| x ^ y }.pack("C*")
+    end
+
+    # Constant-time equality for two byte strings (false when the lengths differ).
+    def secure_compare(a, b)
+      return false unless a.is_a?(String) && b.is_a?(String) && a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    # Best-effort wipe of a mutable String holding secret material. Ruby cannot guarantee
+    # that no copies remain; this merely shortens the window for the buffer we own.
+    def wipe(str)
+      return str unless str.is_a?(String) && !str.frozen?
+
+      str.replace("\0" * str.bytesize)
+      str.clear
+    end
+
+    # Force a binary-encoded copy of a string without mutating the argument.
+    def binary(str)
+      str.b
+    end
+  end
+end

data/lib/sqrl/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SQRL
+  # Version shared by every gem in the family.
+  VERSION = "0.1.0"
+end

data/lib/sqrl.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "sqrl/version"
+require_relative "sqrl/errors"
+require_relative "sqrl/util"
+require_relative "sqrl/crypto"
+require_relative "sqrl/identity"
+
+# SQRL (Secure Quick Reliable Login) for Ruby.
+module SQRL
+  autoload :Storage, "sqrl/storage"
+  autoload :S4Identity, "sqrl/storage"
+  autoload :Textual, "sqrl/textual"
+  autoload :URL, "sqrl/url"
+  autoload :Protocol, "sqrl/protocol"
+  autoload :Tif, "sqrl/protocol"
+  autoload :Command, "sqrl/protocol"
+  autoload :ClientOptions, "sqrl/protocol"
+  autoload :Ask, "sqrl/protocol"
+  autoload :ServerResponse, "sqrl/protocol"
+  autoload :Session, "sqrl/protocol/session"
+  autoload :Server, "sqrl/server" # SQRL::Server::Redis needs an explicit require "sqrl/server/redis"
+  autoload :TestVectors, "sqrl/test_vectors"
+end