touchque 5.0.0

data/lib/touchque/util.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module Touchque
+  # Small helpers shared by the SDK (no third-party gems).
+  module Util
+    module_function
+
+    def b64url(bytes)
+      [bytes].pack("m0").tr("+/", "-_").delete("=")
+    end
+
+    def b64url_decode(text)
+      s = text.to_s.tr("-_", "+/")
+      s += "=" * ((4 - s.length % 4) % 4)
+      s.unpack1("m0")
+    rescue ArgumentError
+      raise ArgumentError, "malformed base64url"
+    end
+
+    def b64_decode(text)
+      text.to_s.unpack1("m0")
+    end
+
+    def sha256(data)
+      OpenSSL::Digest::SHA256.digest(data)
+    end
+
+    def sha256_hex(data)
+      OpenSSL::Digest::SHA256.hexdigest(data)
+    end
+
+    def hmac_hex(key, data)
+      OpenSSL::HMAC.hexdigest("SHA256", key, data)
+    end
+
+    def hmac(key, data)
+      OpenSSL::HMAC.digest("SHA256", key, data)
+    end
+
+    # Constant-time string comparison.
+    def secure_compare(a, b)
+      a = a.to_s.b
+      b = b.to_s.b
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def random_hex(bytes = 16)
+      SecureRandom.hex(bytes)
+    end
+
+    # A path segment, percent-encoded (encodeURIComponent / rawurlencode).
+    def seg(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    # JSON text, compact, non-ASCII kept as is (like JSON.stringify).
+    def json(value)
+      JSON.generate(value)
+    end
+
+    def parse_json(text)
+      return nil if text.nil? || text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Keys as strings, deeply (symbol keys from Ruby callers become the API's names).
+    def stringify(value)
+      case value
+      when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify(v) }
+      when Array then value.map { |v| stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    # A hash without nil values (and, for strings, without empty ones).
+    def compact(hash)
+      hash.reject { |_, v| v.nil? || (v.is_a?(String) && v.empty?) }
+    end
+
+    # The bytes JSON.stringify would write for a string (quotes included).
+    def js_string(str)
+      out = +'"'
+      str.to_s.each_char do |c|
+        out << case c
+               when '"' then '\\"'
+               when "\\" then "\\\\"
+               when "\b" then "\\b"
+               when "\f" then "\\f"
+               when "\n" then "\\n"
+               when "\r" then "\\r"
+               when "\t" then "\\t"
+               else
+                 c.ord < 0x20 ? format("\\u%04x", c.ord) : c
+               end
+      end
+      out << '"'
+    end
+
+    # JSON text without insignificant whitespace; strings and numbers kept byte for byte.
+    def compact_json(text)
+      out = +""
+      in_string = false
+      escaped = false
+      text.each_char do |c|
+        if in_string
+          out << c
+          if escaped
+            escaped = false
+          elsif c == "\\"
+            escaped = true
+          elsif c == '"'
+            in_string = false
+          end
+        elsif c == '"'
+          in_string = true
+          out << c
+        elsif !" \t\n\r".include?(c)
+          out << c
+        end
+      end
+      out
+    end
+
+    # The members of a top-level JSON object as [key, raw value text] pairs, in order.
+    def top_level_members(text)
+      s = text.strip
+      raise JSON::ParserError, "not an object" unless s.start_with?("{")
+
+      members = []
+      i = 1
+      loop do
+        i = skip_ws(s, i)
+        break if s[i] == "}"
+
+        key_end = scan_string(s, i)
+        key = JSON.parse("[#{s[i...key_end]}]")[0]
+        i = skip_ws(s, key_end)
+        raise JSON::ParserError, "expected :" unless s[i] == ":"
+
+        i = skip_ws(s, i + 1)
+        value_end = scan_value(s, i)
+        members << [key, s[i...value_end]]
+        i = skip_ws(s, value_end)
+        if s[i] == ","
+          i += 1
+        elsif s[i] == "}"
+          break
+        else
+          raise JSON::ParserError, "expected , or }"
+        end
+      end
+      members
+    end
+
+    def skip_ws(s, i)
+      i += 1 while i < s.length && " \t\n\r".include?(s[i])
+      i
+    end
+
+    def scan_string(s, i)
+      raise JSON::ParserError, "expected a string" unless s[i] == '"'
+
+      i += 1
+      while i < s.length
+        case s[i]
+        when "\\" then i += 2
+        when '"' then return i + 1
+        else i += 1
+        end
+      end
+      raise JSON::ParserError, "unterminated string"
+    end
+
+    def scan_value(s, i)
+      case s[i]
+      when '"' then scan_string(s, i)
+      when "{", "["
+        depth = 0
+        while i < s.length
+          case s[i]
+          when '"'
+            i = scan_string(s, i)
+            next
+          when "{", "[" then depth += 1
+          when "}", "]"
+            depth -= 1
+            return i + 1 if depth.zero?
+          end
+          i += 1
+        end
+        raise JSON::ParserError, "unterminated value"
+      else
+        j = i
+        j += 1 while j < s.length && !",}".include?(s[j])
+        j -= 1 while j > i && " \t\n\r".include?(s[j - 1])
+        j
+      end
+    end
+
+    # True for https, and for plaintext http only on this machine (localhost, 127.0.0.1,
+    # ::1, *.localhost: local development).
+    def https_or_loopback?(url)
+      uri = URI.parse(url.to_s)
+      return true if uri.scheme == "https"
+
+      host = uri.hostname.to_s.downcase
+      uri.scheme == "http" && (%w[localhost 127.0.0.1 ::1].include?(host) || host.end_with?(".localhost"))
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Allow plaintext http only for localhost / loopback (local development).
+    def assert_safe_url!(url, name)
+      uri = URI.parse(url.to_s)
+      return if uri.scheme == "https"
+
+      if uri.scheme == "http"
+        return if %w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host.to_s.downcase)
+
+        raise ConfigError, "Refusing a plaintext http:// #{name} for \"#{uri.host}\". The API key and request signature would be sent in the clear: use https://."
+      end
+      raise ConfigError, "#{name} must be http(s): #{url}"
+    rescue URI::InvalidURIError
+      raise ConfigError, "#{name} is not a valid URL: #{url}"
+    end
+
+    def now
+      Time.now.to_i
+    end
+
+    def now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+
+    # Unix seconds of an ISO 8601 timestamp, or nil.
+    def parse_time(value)
+      return nil unless value.is_a?(String) && !value.empty?
+
+      require "time"
+      Time.iso8601(value).to_f
+    rescue ArgumentError
+      begin
+        Time.parse(value).to_f
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/touchque/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Touchque
+  VERSION = "5.0.0"
+end

data/lib/touchque.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "touchque/version"
+require_relative "touchque/errors"
+require_relative "touchque/util"
+require_relative "touchque/http"
+require_relative "touchque/crypto"
+require_relative "touchque/approvals"
+require_relative "touchque/code_reply"
+require_relative "touchque/safe_approval"
+require_relative "touchque/resources/login"
+require_relative "touchque/resources/actions"
+require_relative "touchque/resources/people"
+require_relative "touchque/resources/agents"
+require_relative "touchque/resources/identity"
+require_relative "touchque/resources/mobile"
+require_relative "touchque/resources/qr_pairings"
+require_relative "touchque/resources/device_risk"
+require_relative "touchque/resources/safe_guard"
+require_relative "touchque/resources/webhook"
+require_relative "touchque/flow"
+require_relative "touchque/client"
+require_relative "touchque/relay"
+require_relative "touchque/agent"
+require_relative "touchque/org_agent"
+require_relative "touchque/cross_app_access"
+require_relative "touchque/security_events"
+require_relative "touchque/agent_card"
+require_relative "touchque/hosted_login"
+require_relative "touchque/login_session"
+
+# Touchque: push approvals with number matching, passkeys, silent sign-ins, offline
+# codes, verified webhooks, Touchque Actions, AI agent approvals, Touchque Login and the
+# server side of the Mobile SDK.
+#
+#   # TQ_API_KEY=tq_...  TQ_API_SECRET=...
+#   step = Touchque.client.start("SEND_MONEY", "jane@acme.com", details: { "Amount" => "250 EUR" })
+module Touchque
+  @lock = Mutex.new
+
+  class << self
+    attr_writer :client, :replay_cache, :hosted_login, :login_secret
+
+    # Where the SDK reports its own problems: a misconfigured guard, a failed on_challenge,
+    # a relay without get_login_user. nil (the default) logs nothing; set any Logger
+    # (Touchque.logger = Rails.logger). Lines carry an error's class and message, never
+    # request data.
+    attr_accessor :logger
+
+    # @api private: one of the SDK's own problems (:warn or :error) to Touchque.logger, if any.
+    # A logger that raises never breaks the request.
+    def log(level, message)
+      logger&.public_send(level, message)
+    rescue StandardError
+      nil
+    end
+
+    # Options for Touchque.client (api_key:, api_secret:, base_url:, timeout:); anything
+    # left out comes from the environment.
+    def configure(**options)
+      @lock.synchronize do
+        @client_options = options
+        @client = nil
+      end
+    end
+
+    # The shared client, built on first use from configure or the environment.
+    def client
+      @client || @lock.synchronize { @client ||= Client.new(**(@client_options || {})) }
+    end
+
+    # Webhook jtis already accepted (in-process by default; set one over Redis when you
+    # run several processes: anything answering check_and_set(jti, ttl_seconds)).
+    def replay_cache
+      @replay_cache || @lock.synchronize { @replay_cache ||= MemoryReplayCache.new }
+    end
+
+    # Touchque Login settings: domain:, client_id:, client_secret:, scope:, audience:,
+    # redirect_uri:, callback_path:, login_path:, post_logout_redirect_uri:, session_max_age:.
+    def login_options=(options)
+      @login_options = Util.stringify(options || {}).transform_keys(&:to_sym)
+      @hosted_login = nil
+    end
+
+    def login_options
+      @login_options || {}
+    end
+
+    # The Touchque Login client of login_options.
+    def hosted_login
+      @hosted_login || @lock.synchronize do
+        @hosted_login ||= begin
+          o = login_options
+          raise ConfigError, "Set config.touchque.login (domain:, client_id:) or Touchque.login_options" if o[:domain].to_s.empty?
+
+          HostedLogin.new(domain: o[:domain], client_id: o[:client_id], client_secret: o[:client_secret],
+                          scope: o[:scope] || "openid profile email", audience: o[:audience],
+                          redirect_uri: o[:redirect_uri].to_s.match?(%r{\Ahttps?://}) ? o[:redirect_uri] : nil)
+        end
+      end
+    end
+
+    # The secret that encrypts the Touchque Login cookies (at least 32 characters).
+    def login_secret
+      secret = @login_secret.respond_to?(:call) ? @login_secret.call : @login_secret
+      raise ConfigError, "Set Touchque.login_secret (32+ characters) for the Touchque Login cookies" if secret.to_s.length < 32
+
+      secret
+    end
+  end
+
+  # The relay as a Rack app (Sinatra, plain Rack), loaded on first use: Rack is not a
+  # dependency of the gem.
+  module Rack
+    autoload :Relay, File.expand_path("touchque/rack/relay", __dir__)
+  end
+end
+
+if defined?(Rails::Railtie)
+  require_relative "touchque/rack/relay"
+  require_relative "touchque/rails/guard"
+  require_relative "touchque/rails/hosted_login"
+  require_relative "touchque/railtie"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: touchque
+version: !ruby/object:Gem::Version
+  version: 5.0.0
+platform: ruby
+authors:
+- Touchque
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Server SDK for Touchque Authenticator and Touchque Login, with Rails
+  integration (Railtie, controller concerns) and a Rack relay for @touchque/web.
+email:
+- developer@touchque.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/touchque.rb
+- lib/touchque/agent.rb
+- lib/touchque/agent_card.rb
+- lib/touchque/approvals.rb
+- lib/touchque/client.rb
+- lib/touchque/code_reply.rb
+- lib/touchque/cross_app_access.rb
+- lib/touchque/crypto.rb
+- lib/touchque/errors.rb
+- lib/touchque/flow.rb
+- lib/touchque/hosted_login.rb
+- lib/touchque/http.rb
+- lib/touchque/login_session.rb
+- lib/touchque/org_agent.rb
+- lib/touchque/rack/relay.rb
+- lib/touchque/rails/guard.rb
+- lib/touchque/rails/hosted_login.rb
+- lib/touchque/rails/sessions_controller.rb
+- lib/touchque/railtie.rb
+- lib/touchque/relay.rb
+- lib/touchque/resources/actions.rb
+- lib/touchque/resources/agents.rb
+- lib/touchque/resources/device_risk.rb
+- lib/touchque/resources/identity.rb
+- lib/touchque/resources/login.rb
+- lib/touchque/resources/mobile.rb
+- lib/touchque/resources/people.rb
+- lib/touchque/resources/qr_pairings.rb
+- lib/touchque/resources/safe_guard.rb
+- lib/touchque/resources/webhook.rb
+- lib/touchque/safe_approval.rb
+- lib/touchque/security_events.rb
+- lib/touchque/util.rb
+- lib/touchque/version.rb
+homepage: https://touchque.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Touchque/touchque-ruby
+  changelog_uri: https://github.com/Touchque/touchque-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://support.touchque.com
+  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: 4.0.23
+specification_version: 4
+summary: 'Official Ruby SDK for Touchque: push approvals with number matching, passkeys,
+  silent sign-ins, webhooks, Actions, AI agents and Touchque Login.'
+test_files: []