touchque 5.0.0

data/lib/touchque/agent.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Touchque
+  # Plain HTTP for the clients that do not sign with the API key (agents, Touchque
+  # Login, MCP). Never follows redirects.
+  module Transport
+    module_function
+
+    # [status, body text, response].
+    def call(method, url, headers: {}, body: nil, timeout: 10)
+      uri = URI.parse(url)
+      klass = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post, "PUT" => Net::HTTP::Put,
+                "PATCH" => Net::HTTP::Patch, "DELETE" => Net::HTTP::Delete }.fetch(method.to_s.upcase)
+      req = klass.new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req["Accept"] ||= "application/json"
+      req.body = body unless body.nil?
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      res = http.request(req)
+      raise NetworkError, "the answer is larger than 10 MB" if res.body.to_s.bytesize > HTTP::MAX_RESPONSE_BYTES
+
+      [res.code.to_i, res.body.to_s.dup.force_encoding("UTF-8"), res]
+    rescue *HTTP::NETWORK_ERRORS => e
+      raise NetworkError, e.message
+    end
+
+    def form(fields)
+      URI.encode_www_form(fields.reject { |_, v| v.nil? || v.to_s.empty? })
+    end
+
+    # An OAuth-style error answer as APIError (code = error, retryAfter from retry_after).
+    def oauth_failure(status, data)
+      data = data.is_a?(Hash) ? data : {}
+      data["code"] ||= data["error"]
+      data["retryAfter"] ||= data["retry_after"].to_i if data["retry_after"]
+      APIError.for(status, data, data["error_description"] || data["error"] || "Touchque API error: HTTP #{status}")
+    end
+  end
+
+  # The agent side: an AI agent calls Touchque with its OWN key, never with your API
+  # key. It signs a private_key_jwt assertion (RFC 7523) for a 10-minute token bound to
+  # its key with DPoP (RFC 9449), and proves the key on every call, so a stolen token is
+  # useless on its own.
+  #
+  #   agent = Touchque::Agent.new          # TQ_AGENT_ID, TQ_AGENT_KEY (a JWK as JSON, or an EC PEM)
+  #   approved = agent.require_approval("ayse@acme.com", "PAY_INVOICE", [payment]) do |state|
+  #     say "Type #{state["challengeCode"]} on your phone"
+  #   end
+  class Agent
+    ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+    ENDED = %w[rejected blocked revoked expired stale redeemed].freeze
+
+    attr_reader :agent_id
+
+    def initialize(agent_id: nil, private_key: nil, kid: nil, base_url: nil, scope: nil, timeout: 10)
+      agent_id ||= ENV.fetch("TQ_AGENT_ID", "")
+      raise ConfigError, "Set TQ_AGENT_ID (or agent_id:): the agt_... id from agents.create" unless agent_id.match?(/\Aagt_[a-z2-9]{20}\z/)
+
+      private_key ||= ENV.fetch("TQ_AGENT_KEY", nil)
+      raise ConfigError, "Set TQ_AGENT_KEY (or private_key:): the agent's private key" if private_key.nil? || private_key.to_s.empty?
+
+      @agent_id = agent_id
+      @key = SigningKey.load(private_key, "Touchque::Agent")
+      jwk = private_key.is_a?(Hash) ? Util.stringify(private_key) : (private_key.to_s.lstrip.start_with?("{") ? Util.parse_json(private_key) : nil)
+      @kid = kid || (jwk.is_a?(Hash) && jwk["kid"]) || AgentKeys.thumbprint(@key.public_jwk)
+      @base_url = (base_url || (ENV["TQ_API_URL"].to_s.empty? ? DEFAULT_BASE_URL : ENV.fetch("TQ_API_URL"))).chomp("/")
+      Util.assert_safe_url!(@base_url, "base_url")
+      @scope = scope
+      @timeout = timeout
+      @token = nil
+      @expires_at = 0
+      @lock = Mutex.new
+    end
+
+    # The agent's current token (renewed a minute before it expires).
+    def access_token
+      @lock.synchronize do
+        return @token if @token && @expires_at - Util.now > 60
+
+        fetch_token
+      end
+    end
+
+    # The agent as Touchque sees it: its action types, owner, review date and workspace.
+    def me
+      request("GET", "/agents/me")
+    end
+
+    # Asks the person to approve on their Touchque phone. Show "challengeCode" in your
+    # conversation (presence interactive, the default): the person types it on the phone.
+    # Touchque draws the phone's rows from +authorization_details+ (RFC 9396).
+    # "requiresPasskey" (over the policy's requirePasskeyAbove): the person approves with a
+    # passkey on your page instead, not on the phone.
+    def request_approval(user, type, authorization_details, reason: nil, presence: nil, expires_in: nil, locale: nil,
+                         reference_id: nil, client_ip: nil, user_agent: nil, mandate_id: nil)
+      body = { "externalUsername" => user, "type" => type, "authorizationDetails" => Util.stringify(authorization_details) }
+      { "reason" => reason, "presence" => presence, "expiresIn" => expires_in, "locale" => locale, "referenceId" => reference_id,
+        "clientIp" => client_ip, "userAgent" => user_agent, "mandateId" => mandate_id }.each { |k, v| body[k] = v unless v.nil? }
+      request("POST", "/agents/approvals", body)
+    end
+
+    # Asks the person for a mandate: one approval on the phone for a bounded series of
+    # requests. max_total: { currency: "TRY", amount: "1000" }. Once active, pass
+    # mandate_id: to request_approval: no push.
+    def request_mandate(user, type, max_count, max_total, per_request: nil, recipients: nil, valid_for: nil, reason: nil,
+                        expires_in: nil, locale: nil)
+      body = { "externalUsername" => user, "type" => type, "maxCount" => max_count, "maxTotal" => Util.stringify(max_total) }
+      { "perRequest" => per_request && Util.stringify(per_request), "recipients" => recipients, "validFor" => valid_for, "reason" => reason,
+        "expiresIn" => expires_in, "locale" => locale }.each { |k, v| body[k] = v unless v.nil? }
+      request("POST", "/agents/mandates", body)
+    end
+
+    # The token vault: a person's own access token at another service, for a connection
+    # that names this agent: {"access_token", "token_type" => "Bearer", "expires_in",
+    # "scope", "connection"}. APIError not_connected when nothing is kept.
+    def get_connection_token(user, connection, scope: nil)
+      request("POST", "/agents/vault/token", Util.compact({ "externalUsername" => user, "connection" => connection, "scope" => scope }))
+    end
+
+    def get_mandate(mandate_id)
+      request("GET", "/agents/mandates/#{Util.seg(mandate_id)}")
+    end
+
+    def revoke_mandate(mandate_id)
+      request("POST", "/agents/mandates/#{Util.seg(mandate_id)}/revoke", {})
+    end
+
+    # Where an approval request is; "approvalToken" once approved.
+    def get_approval(approval_id)
+      request("GET", "/agents/approvals/#{Util.seg(approval_id)}")
+    end
+
+    # Asks the person's phone and waits for the answer: the approved state (holding
+    # "approvalToken"), or ApprovalError / TimeoutError. The block (or +on_challenge+)
+    # gets the state while the phone waits: show its "challengeCode". Put it in front of
+    # any tool call an agent framework makes, so the call runs only after the person approved.
+    def require_approval(user, type, authorization_details, on_challenge: nil, timeout: 300, **options, &block)
+      on_challenge ||= block
+      asked = request_approval(user, type, authorization_details, **options)
+      return asked if asked["status"] == "approved" && asked["approvalToken"]
+
+      on_challenge&.call(asked) if asked["challengeCode"]
+      wait_for_approval(asked["approvalId"], timeout: timeout)
+    end
+
+    # Polls until the person approves (the state holding "approvalToken"). ApprovalError
+    # when it ends otherwise, TimeoutError after +timeout+ seconds. An approval given
+    # during a phone call stays provisional until the phone confirms it.
+    def wait_for_approval(approval_id, timeout: 600, interval: 2.0)
+      interval = [interval, 0.5].max
+      deadline = Time.now + timeout
+      loop do
+        state = get_approval(approval_id)
+        return state if state["status"] == "approved" && state["approvalToken"]
+        raise ApprovalError.new(approval_id, state["status"], state["reason"]) if ENDED.include?(state["status"])
+        raise TimeoutError.new("Touchque: approval '#{approval_id}' was not approved within #{timeout}s", approval_id) if Time.now + interval > deadline
+
+        sleep interval
+      end
+    end
+
+    private
+
+    def fetch_token
+      url = "#{@base_url}/agents/token"
+      now = Util.now
+      assertion = @key.jws({ "typ" => "JWT", "kid" => @kid },
+                           { "iss" => @agent_id, "sub" => @agent_id, "aud" => url, "iat" => now, "exp" => now + 60, "jti" => Util.random_hex(16) })
+      form = { "grant_type" => "client_credentials", "client_assertion_type" => ASSERTION_TYPE, "client_assertion" => assertion, "scope" => @scope }
+      status, text, = Transport.call("POST", url, headers: { "Content-Type" => "application/x-www-form-urlencoded", "DPoP" => dpop("POST", url) },
+                                                  body: Transport.form(form), timeout: @timeout)
+      data = Util.parse_json(text)
+      raise Transport.oauth_failure(status, data) unless status == 200 && data.is_a?(Hash) && data["access_token"]
+
+      @token = data["access_token"]
+      @expires_at = Util.now + (data["expires_in"] || 600).to_i
+      @token
+    end
+
+    def dpop(method, url, access_token = nil)
+      claims = { "htm" => method, "htu" => url, "iat" => Util.now, "jti" => Util.random_hex(16) }
+      claims["ath"] = AgentKeys.access_token_hash(access_token) if access_token
+      @key.jws({ "typ" => "dpop+jwt", "jwk" => @key.public_jwk }, claims)
+    end
+
+    # A call with the agent's token and a fresh DPoP proof; one retry with a new token
+    # when Touchque no longer knows it.
+    def request(method, path, body = nil, retried: false)
+      token = access_token
+      url = @base_url + path
+      headers = { "Authorization" => "DPoP #{token}", "DPoP" => dpop(method, url.split("?").first, token) }
+      headers["Content-Type"] = "application/json" unless body.nil?
+      status, text, = Transport.call(method, url, headers: headers, body: body.nil? ? nil : Util.json(body), timeout: @timeout)
+      data = Util.parse_json(text)
+      data = {} unless data.is_a?(Hash)
+      if status == 401 && !retried && data["code"] == "invalid_token"
+        @lock.synchronize { @token = nil if @token == token }
+        return request(method, path, body, retried: true)
+      end
+      raise Transport.oauth_failure(status, data) unless (200..299).cover?(status)
+
+      data
+    end
+  end
+end

data/lib/touchque/agent_card.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Touchque
+  # An A2A agent card that did not verify. +error+ is unsigned, malformed,
+  # untrusted_key, invalid_signature or keys_unavailable.
+  class AgentCardError < Error
+    attr_reader :error
+
+    def initialize(error, message)
+      @error = error
+      super(message)
+    end
+  end
+
+  # A2A agent card signatures (A2A 1.0 §8.4): before your agent trusts another agent's
+  # card (its name, URL, skills), check that whoever controls its keys signed exactly
+  # this card. Each entry of +signatures+ is a JWS (RFC 7515) over the card in RFC 8785
+  # canonical form without +signatures+; the protected header names alg, kid and
+  # optionally jku (where the keys are). Keys come from +keys+ or from the header's
+  # jku, but jku is only followed on the card's own host (or a host in
+  # +trusted_jku_hosts+): a card that points at keys on a host of its choosing proves
+  # nothing. Signers must leave out fields at their default values (A2A §8.4.1); the
+  # card is checked as received.
+  #
+  #   json = Net::HTTP.get(URI("https://agent.example/.well-known/agent-card.json"))
+  #   Touchque::AgentCard.verify(json, card_url: "https://agent.example/.well-known/agent-card.json")
+  module AgentCard
+    ALGS = %w[RS256 ES256 EdDSA].freeze
+
+    module_function
+
+    # A number as ECMAScript's Number::toString writes it (RFC 8785 §3.2.2.3).
+    def es_number(value)
+      return value.to_s if value.is_a?(Integer)
+      raise AgentCardError.new("malformed", "a number is not finite") unless value.finite?
+      return "0" if value.zero?
+
+      sign = value.negative? ? "-" : ""
+      mantissa, exp = value.abs.to_s.split(/e/i)
+      int_part, frac = mantissa.split(".")
+      digits = int_part + frac.to_s
+      n = int_part.length + exp.to_i
+      trimmed = digits.sub(/\A0+/, "")
+      n -= digits.length - trimmed.length
+      digits = trimmed.sub(/0+\z/, "")
+      k = digits.length
+      out = if k <= n && n <= 21
+              digits + ("0" * (n - k))
+            elsif n.positive? && n <= 21
+              "#{digits[0, n]}.#{digits[n..]}"
+            elsif n > -6 && n <= 0
+              "0.#{"0" * -n}#{digits}"
+            else
+              x = n - 1
+              "#{digits[0]}#{k > 1 ? ".#{digits[1..]}" : ""}e#{x >= 0 ? "+" : "-"}#{x.abs}"
+            end
+      sign + out
+    end
+
+    # RFC 8785 (JSON Canonicalization Scheme): sorted keys (UTF-16 order), no whitespace, ECMAScript numbers.
+    def canonical_json(value)
+      case value
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when String then Util.js_string(value)
+      when Integer, Float then es_number(value)
+      when Array then "[#{value.map { |v| canonical_json(v) }.join(",")}]"
+      when Hash
+        keys = value.keys.map(&:to_s).sort_by { |k| k.encode("UTF-16BE").b }
+        h = Util.stringify(value)
+        "{#{keys.map { |k| "#{Util.js_string(k)}:#{canonical_json(h[k])}" }.join(",")}}"
+      else
+        raise AgentCardError.new("malformed", "cannot canonicalize #{value.class}")
+      end
+    end
+
+    def decode(card)
+      c = card.is_a?(String) ? Util.parse_json(card) : Util.stringify(card)
+      raise AgentCardError.new("malformed", "the card is not a JSON object") unless c.is_a?(Hash)
+
+      c
+    end
+
+    def payload(card)
+      Util.b64url(canonical_json(card.reject { |k, _| k == "signatures" }))
+    end
+
+    def host_of(url)
+      return nil unless url && CrossAppAccess.safe_url?(url)
+
+      u = URI.parse(url)
+      u.port == u.default_port ? u.host : "#{u.host}:#{u.port}"
+    end
+
+    # Checks the card's signatures: { "kid", "alg", "key_source" => "keys" | "jku" } or AgentCardError.
+    def verify(card, card_url: nil, keys: nil, trusted_jku_hosts: [], fetch: nil)
+      c = decode(card)
+      sigs = c["signatures"]
+      raise AgentCardError.new("unsigned", "the card has no signatures") unless sigs.is_a?(Array) && !sigs.empty?
+
+      given = Util.stringify(keys.is_a?(Hash) ? (keys["keys"] || keys[:keys] || []) : (keys || []))
+      card_host = host_of(card_url)
+      fetch ||= CrossAppAccess.method(:get_json)
+      body = payload(c)
+      last = AgentCardError.new("invalid_signature", "no signature verifies")
+      sigs.each do |s|
+        next unless s.is_a?(Hash) && s["protected"].is_a?(String) && s["signature"].is_a?(String)
+
+        head = Util.parse_json(Util.b64url_decode(s["protected"]).force_encoding("UTF-8"))
+        next unless head.is_a?(Hash)
+
+        alg = head["alg"]
+        next unless ALGS.include?(alg) && head["kid"].is_a?(String) && !head.key?("crit")
+        next if head.key?("typ") && head["typ"] != "JOSE"
+
+        jwk = given.find { |k| k["kid"] == head["kid"] }
+        source = "keys"
+        if jwk.nil? && head["jku"].is_a?(String)
+          jku_host = host_of(head["jku"])
+          unless jku_host && (jku_host == card_host || Array(trusted_jku_hosts).include?(jku_host))
+            last = AgentCardError.new("untrusted_key", "jku #{head["jku"]} is not on the card's host")
+            next
+          end
+          begin
+            jwk = (fetch.call(head["jku"])["keys"] || []).find { |k| k["kid"] == head["kid"] }
+          rescue StandardError => e
+            last = AgentCardError.new("keys_unavailable", "the keys at #{head["jku"]} could not be read: #{e.message}")
+            next
+          end
+          source = "jku"
+        end
+        if jwk.nil?
+          last = AgentCardError.new("untrusted_key", "no trusted key #{head["kid"]}") if last.error == "invalid_signature"
+          next
+        end
+        return { "kid" => head["kid"], "alg" => alg, "key_source" => source } if JWS.verify(alg, jwk, "#{s["protected"]}.#{body}", Util.b64url_decode(s["signature"]))
+
+        last = AgentCardError.new("invalid_signature", "the signature does not match the card")
+      rescue ArgumentError
+        next
+      end
+      raise last
+    end
+
+    # Signs a card you publish: the card JSON with one more entry in +signatures+.
+    # The key is an ES256 or EdDSA private JWK (Hash or JSON) or an EC P-256 PEM.
+    def sign(card, private_key, kid:, jku: nil)
+      c = decode(card)
+      key = SigningKey.load(private_key, "AgentCard.sign")
+      header = { "alg" => key.alg, "typ" => "JOSE", "kid" => kid }
+      header["jku"] = jku if jku
+      protected_header = Util.b64url(Util.json(header))
+      sig = key.sign("#{protected_header}.#{payload(c)}")
+      c["signatures"] = Array(c["signatures"]) + [{ "protected" => protected_header, "signature" => Util.b64url(sig) }]
+      Util.json(c)
+    end
+  end
+end

data/lib/touchque/approvals.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Touchque
+  # Transaction details the way the API normalizes and digests them.
+  module Details
+    # What JavaScript's trim removes, as the API trims: ASCII and Unicode spaces (U+00A0,
+    # U+202F...), line separators and the BOM. String#strip knows only the ASCII ones.
+    SPACE = "[\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]"
+    TRIM = /\A#{SPACE}+|#{SPACE}+\z/
+
+    module_function
+
+    # A Hash ({"Amount" => "250 EUR"}) or a list of {label:, value:} as
+    # [{"label", "value"}] with trimmed strings.
+    def normalize(details)
+      return [] if details.nil? || details.empty?
+
+      pairs = if details.is_a?(Hash)
+                details.map { |label, value| [label.to_s, value.to_s] }
+              else
+                details.map do |d|
+                  d = Util.stringify(d)
+                  [d["label"].to_s, d["value"].to_s]
+                end
+              end
+      pairs.map { |label, value| { "label" => trim(label), "value" => trim(value) } }
+    end
+
+    def trim(text)
+      text.ascii_only? || text.encoding == Encoding::UTF_8 ? text.gsub(TRIM, "") : text.strip
+    end
+
+    # SHA-256 (hex) over the normalized details joined as label US value RS label...;
+    # "" for no details. The phone signs this digest (ApprovalProof).
+    def digest(details)
+      pairs = normalize(details)
+      return "" if pairs.empty?
+
+      Util.sha256_hex(pairs.map { |p| "#{p["label"]}\u001f#{p["value"]}" }.join("\u001e"))
+    end
+  end
+
+  # Verifies the device-signed proof of an approval ("what you see is what you sign").
+  # When the phone holds a hardware key (Secure Enclave / Android Keystore), every
+  # approval is signed over the request id, the action type, the number-match code and
+  # a digest of the details the user was shown. The proof arrives in the SUCCESS webhook
+  # ("approvalProof") and in the consumed approval. Verifying it does not require
+  # trusting Touchque.
+  module ApprovalProof
+    PREFIX = "touchque-approve:v2"
+
+    module_function
+
+    # True only if +proof+ was signed by the device key over exactly the request, action
+    # type, challenge code and details you expect. Pin the device with
+    # +expected_public_key+ (the base64 key you stored for this user), or pass
+    # allow_unpinned_key: true for trust on first use. Never raises.
+    def verify(proof, request_id:, type:, details: nil, challenge_code: nil, expected_public_key: nil, allow_unpinned_key: false)
+      return false unless proof.is_a?(Hash)
+
+      proof = Util.stringify(proof)
+      return false unless proof["version"] == "v2" && proof["algorithm"] == "ECDSA-P256-SHA256"
+
+      public_key = proof["publicKey"]
+      message = proof["message"]
+      signature = proof["signature"]
+      return false unless [public_key, message, signature].all?(String)
+
+      if expected_public_key && !expected_public_key.empty?
+        return false unless Util.secure_compare(expected_public_key, public_key)
+      elsif allow_unpinned_key != true
+        return false
+      end
+      expected = [PREFIX, request_id.to_s, type.to_s, challenge_code.to_s, Details.digest(details)].join("\n")
+      return false unless Util.secure_compare(expected, message)
+
+      raw = public_key.unpack1("m0")
+      return false unless raw.bytesize == 65 && raw.getbyte(0) == 4
+
+      sig = signature.unpack1("m0")
+      return false if sig.empty?
+
+      key = OpenSSL::PKey.read(AgentKeys::P256_SPKI + raw)
+      key.verify(OpenSSL::Digest.new("SHA256"), sig, message)
+    rescue StandardError
+      false
+    end
+  end
+
+  # What a partner's server checks before executing what an AI agent asked for: the
+  # approval token's claims match the transaction (person, action type, authorization
+  # details) and, offline, its ES256 signature against Touchque's keys
+  # (GET /agents/jwks.json). Amounts compare as decimals ("500" = "500.00"), IBANs
+  # without spaces in any case, currencies in any case; a Hash matches a token with
+  # exactly one entry, an Array matches entry by entry.
+  module ApprovalToken
+    module_function
+
+    # {"header", "claims"} WITHOUT checking the signature.
+    def decode(token)
+      parts = JWS.split(token)
+      raise ApprovalMismatchError, "not an approval token" unless parts
+
+      { "header" => parts[0], "claims" => parts[1] }
+    end
+
+    # Does +details+ (a token's authorization_details) say what +expected+ says?
+    def matches?(details, expected)
+      return false unless details.is_a?(Array)
+
+      expected = Util.stringify(expected)
+      if expected.is_a?(Array)
+        return false unless details.length == expected.length
+
+        return expected.each_with_index.all? { |e, i| partial(details[i], e) }
+      end
+      details.length == 1 && partial(details[0], expected)
+    end
+
+    # Raises ApprovalMismatchError unless the claims say what you expect.
+    def assert_matches!(claims, user: nil, type: nil, authorization_details: nil)
+      if user && claims["sub"] != user
+        raise ApprovalMismatchError, "the approval is for another person"
+      end
+      if type && claims["type"] != type
+        raise ApprovalMismatchError, "the approval is for another action type (#{claims["type"]})"
+      end
+      if authorization_details && !matches?(claims["authorization_details"], authorization_details)
+        raise ApprovalMismatchError, "the approved details differ from what you are about to execute"
+      end
+
+      true
+    end
+
+    # Verifies an approval token offline: typ touchque-approval+jwt, ES256 by a key of
+    # +jwks+, not expired (30 s leeway), aud equal to +audience+, then the expectation.
+    # +audience+ is required: /agents/jwks.json is one key set for every Touchque
+    # workspace, so without it a token Touchque signed for another workspace would pass.
+    # Pass your own (tq.agents.approval_audience, touchque:workspace:<id>), or use
+    # tq.agents.verify_approval_token, which fills it in.
+    # Does NOT make it single-use: agents.redeem_approval does.
+    def verify_with(token, jwks, audience: nil, user: nil, type: nil, authorization_details: nil, now: nil)
+      if !audience.is_a?(String) || audience.empty?
+        raise ApprovalMismatchError, "audience is required: your workspace's touchque:workspace:<id> (tq.agents.approval_audience)"
+      end
+      parts = JWS.split(token)
+      raise ApprovalMismatchError, "not an approval token" unless parts
+
+      header, claims, input, sig = parts
+      unless header["typ"] == "touchque-approval+jwt" && header["alg"] == "ES256"
+        raise ApprovalMismatchError, "not an approval token (typ/alg)"
+      end
+
+      jwk = (Util.stringify(jwks)["keys"] || []).reverse.find do |k|
+        k["kid"] == header["kid"] && k["kty"] == "EC" && k["crv"] == "P-256"
+      end
+      raise ApprovalMismatchError, "signed by an unknown key" unless jwk
+      raise ApprovalMismatchError, "the signature does not verify" unless JWS.verify("ES256", jwk, input, sig)
+
+      exp = claims["exp"]
+      raise ApprovalMismatchError, "the approval token expired" unless exp.is_a?(Numeric) && exp + 30 >= (now || Util.now)
+      aud = claims["aud"]
+      raise ApprovalMismatchError, "the approval token names no workspace" if !aud.is_a?(String) || aud.empty?
+      raise ApprovalMismatchError, "the approval token is for another workspace" if aud != audience
+
+      assert_matches!(claims, user: user, type: type, authorization_details: authorization_details)
+      claims
+    end
+
+    def decimal(value)
+      text = value.to_s.strip
+      return nil unless text.match?(/\A\d+(\.\d+)?\z/)
+
+      whole, frac = text.split(".", 2)
+      whole = whole.sub(/\A0+/, "")
+      whole = "0" if whole.empty?
+      frac = (frac || "").sub(/0+\z/, "")
+      frac.empty? ? whole : "#{whole}.#{frac}"
+    end
+
+    def same(key, actual, expected)
+      return partial(actual, expected) if expected.is_a?(Hash) || expected.is_a?(Array)
+
+      case key
+      when "amount"
+        !decimal(actual).nil? && decimal(actual) == decimal(expected)
+      when "iban", "currency"
+        actual.is_a?(String) && actual.gsub(/\s+/, "").upcase == expected.to_s.gsub(/\s+/, "").upcase
+      else
+        scalar_equal(actual, expected)
+      end
+    end
+
+    def partial(actual, expected)
+      if expected.is_a?(Array)
+        return false unless actual.is_a?(Array) && actual.length == expected.length
+
+        return expected.each_with_index.all? do |e, i|
+          e.is_a?(Hash) || e.is_a?(Array) ? partial(actual[i], e) : scalar_equal(actual[i], e)
+        end
+      end
+      return scalar_equal(actual, expected) unless expected.is_a?(Hash)
+      return false unless actual.is_a?(Hash)
+
+      expected.all? { |k, v| actual.key?(k) && same(k, actual[k], v) }
+    end
+
+    def scalar_equal(a, b)
+      return a == b unless a.is_a?(Numeric) && b.is_a?(Numeric)
+
+      a.to_r == b.to_r
+    end
+  end
+end

data/lib/touchque/client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Touchque
+  DEFAULT_BASE_URL = "https://api.touchque.com"
+
+  # The Touchque client. Every call is signed with your API secret, so it belongs on
+  # your server; browser pieces relay through it.
+  #
+  #   # TQ_API_KEY=tq_...  TQ_API_SECRET=...
+  #   tq = Touchque::Client.new
+  #   step = tq.start("SEND_MONEY", "jane@acme.com", details: { "Amount" => "250 EUR" })
+  #
+  # Thread-safe: create one and reuse it (in Rails, Touchque.client).
+  class Client
+    attr_reader :auth, :login, :webauthn, :webhook, :offline, :action_types, :actions, :risk, :recovery,
+                :assist, :agents, :identity, :mobile, :qr_pairings, :device_risk, :safe_guard
+
+    # Anything left nil falls back to the environment: TQ_API_KEY, TQ_API_SECRET and
+    # TQ_API_URL (default https://api.touchque.com). +timeout+ is seconds per request.
+    def initialize(api_key: nil, api_secret: nil, base_url: nil, timeout: 10)
+      api_key ||= ENV.fetch("TQ_API_KEY", nil)
+      api_secret ||= ENV.fetch("TQ_API_SECRET", nil)
+      base_url ||= ENV["TQ_API_URL"].to_s.empty? ? DEFAULT_BASE_URL : ENV.fetch("TQ_API_URL")
+      if api_key.to_s.empty? || api_secret.to_s.empty?
+        raise ConfigError, "Set TQ_API_KEY and TQ_API_SECRET (or pass api_key: and api_secret:)."
+      end
+      raise ConfigError, "api_key must start with \"tq_\". Did you accidentally swap api_key and api_secret?" unless api_key.start_with?("tq_")
+
+      Util.assert_safe_url!(base_url, "base_url")
+      @http = HTTP.new(api_key: api_key, api_secret: api_secret, base_url: base_url.chomp("/"), timeout: timeout)
+      @auth = Resources::Auth.new(@http)
+      @login = Resources::Login.new(@http)
+      @webauthn = Resources::WebAuthn.new(@http)
+      @webhook = Resources::Webhook.new(api_secret)
+      @offline = Resources::Offline.new(@http)
+      @action_types = Resources::ActionTypes.new(@http)
+      @actions = Resources::Actions.new(@http)
+      @risk = Resources::Risk.new(@http)
+      @recovery = Resources::Recovery.new(@http)
+      @assist = Resources::Assist.new(@http)
+      @agents = Resources::Agents.new(@http)
+      @identity = Resources::Identity.new(@http)
+      @mobile = Resources::Mobile.new(@http)
+      @qr_pairings = Resources::QrPairings.new(@http)
+      @device_risk = Resources::DeviceRisk.new(@http)
+      @safe_guard = Resources::SafeGuard.new(@http)
+    end
+
+    # @api private: signs the guard tokens.
+    def api_secret
+      @http.api_secret
+    end
+
+    # Starts an approval and returns at once: show the step in your UI. "waiting" with
+    # "number": show the number, the user picks it on the phone. "enroll": show
+    # step["enroll"]["qrCodeDataUrl"] so the user links the Touchque app first.
+    # +browser_proof+ (silent sign-ins): the X-Touchque-Browser header, passed through.
+    def start(action, user, details: nil, reference_id: nil, ip: nil, user_agent: nil, browser_proof: nil, context: nil)
+      Steps.start(self, action, user, details: details, reference_id: reference_id, ip: ip, user_agent: user_agent,
+                                      browser_proof: browser_proof, context: context)
+    end
+
+    # Where a started approval is now: waiting, approved, rejected, expired...
+    def check(request_id)
+      Steps.check(self, request_id)
+    end
+
+    # Uses an approved request exactly once, after checking it is for this user, action
+    # and transaction. Call it right before doing the protected thing.
+    def complete(request_id, user, action, details: nil, reference_id: nil)
+      Steps.complete(self, request_id, user, action, details: details, reference_id: reference_id)
+    end
+
+    # Runs the block only after the user approved on the phone (a push and the wait of
+    # login.verify).
+    def protect(user, type: "LOGIN", **options)
+      login.verify(user, type: type, **options)
+      yield
+    end
+  end
+end