touchque 5.0.0

data/lib/touchque/errors.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Touchque
+  # Base class of every error the SDK raises.
+  class Error < StandardError; end
+
+  # Touchque answered with an error (status 400 or more). +status+ is the HTTP
+  # status, +code+ the machine-readable code (+device_not_linked+,
+  # +unknown_action+, +already_used+...) and +data+ the decoded JSON body.
+  class APIError < Error
+    attr_reader :status, :data
+
+    def initialize(status, data = nil, message = nil)
+      @status = status
+      @data = data.is_a?(Hash) ? data : {}
+      super(message || @data["message"] || @data["error"] || "Touchque API error: HTTP #{status}")
+    end
+
+    # Machine-readable error code, e.g. "device_not_linked".
+    def code
+      @data["code"]
+    end
+
+    # The API's +error+ field.
+    def error
+      @data["error"]
+    end
+
+    # Why a request was refused (offline codes, blocked requests).
+    def reason
+      @data["reason"].is_a?(String) ? @data["reason"] : nil
+    end
+
+    # Offline sign: wrong codes left before the challenge locks.
+    def attempts_left
+      @data["attemptsLeft"]
+    end
+
+    # Seconds to wait before retrying (429 / 423).
+    def retry_after
+      @data["retryAfter"]
+    end
+
+    # "Why?" case code of a refusal (+K7P-2QX+): show it to the user ("Tell your
+    # support team: K7P-2QX"); your team opens the decision by it in the dashboard.
+    def case_code
+      @data["caseCode"].is_a?(String) ? @data["caseCode"] : nil
+    end
+
+    # Where to send the person instead (help desk: +never_locked_out+).
+    def route
+      @data["route"]
+    end
+
+    # The error for an answer: a FeatureError subclass for the three feature
+    # codes, else APIError.
+    def self.for(status, data = nil, message = nil)
+      klass = data.is_a?(Hash) ? FeatureError::BY_ERROR[data["error"]] : nil
+      (klass || APIError).new(status, data, message)
+    end
+  end
+
+  # The organization behind your workspace cannot use this feature here (HTTP
+  # 403). +feature_reason+:
+  # - +:not_in_plan+: not in its plan (+feature_not_in_plan+); an owner or admin
+  #   adds it in the Touchque dashboard;
+  # - +:read_only+: being turned off (+feature_read_only+); reads still work for
+  #   14 days, changes are refused;
+  # - +:off+: switched off on this Touchque deployment (+feature_off+).
+  # +feature+ is the catalog id (+device_risk+, +ai_agents+, +mobile_sdk+,
+  # +ciam+...). An APIError, so existing +rescue+ blocks still catch it; rescue
+  # one of the three subclasses to tell them apart.
+  class FeatureError < APIError
+    REASON = nil
+
+    # The catalog id of the feature, or nil.
+    def feature
+      @data["feature"].is_a?(String) ? @data["feature"] : nil
+    end
+
+    # +:not_in_plan+, +:read_only+ or +:off+.
+    def feature_reason
+      self.class::REASON
+    end
+  end
+
+  # +feature_not_in_plan+: the feature is not in the organization's plan.
+  class FeatureNotInPlanError < FeatureError
+    REASON = :not_in_plan
+  end
+
+  # +feature_read_only+: the feature is being turned off; reads work, changes are refused.
+  class FeatureReadOnlyError < FeatureError
+    REASON = :read_only
+  end
+
+  # +feature_off+: the feature is switched off on this Touchque deployment.
+  class FeatureOffError < FeatureError
+    REASON = :off
+  end
+
+  FeatureError::BY_ERROR = {
+    "feature_not_in_plan" => FeatureNotInPlanError,
+    "feature_read_only" => FeatureReadOnlyError,
+    "feature_off" => FeatureOffError,
+  }.freeze
+
+  # The request never reached Touchque (DNS, connection refused, timeout). Unlike
+  # APIError, generally safe to retry.
+  class NetworkError < Error
+    def initialize(message)
+      super("Touchque: network request failed: #{message}")
+    end
+  end
+
+  # The user did not answer in time, or the request expired.
+  class TimeoutError < Error
+    attr_reader :request_id
+
+    def initialize(message, request_id = nil)
+      @request_id = request_id
+      super(message)
+    end
+  end
+
+  # The user rejected the request on their phone.
+  class RejectedError < Error
+    attr_reader :request_id
+
+    def initialize(request_id)
+      @request_id = request_id
+      super("Touchque: request '#{request_id}' was rejected by the user.")
+    end
+  end
+
+  # A webhook is not from Touchque, was changed, or is too old.
+  class WebhookSignatureError < Error
+    def initialize(message)
+      super("Touchque: webhook rejected: #{message}")
+    end
+  end
+
+  # A correctly signed webhook with this +jti+ was already accepted. Usually a
+  # Touchque retry of a delivery you processed: answer 200 so it stops, but do not
+  # run your side effects again. A WebhookSignatureError, so existing rescues
+  # still reject it.
+  class WebhookReplayError < WebhookSignatureError
+    attr_reader :jti
+
+    def initialize(jti)
+      @jti = jti
+      super("this webhook (jti) was already accepted")
+    end
+  end
+
+  # Missing or invalid configuration, an undefined action type, or a wrong argument.
+  class ConfigError < Error
+    def initialize(message)
+      super("Touchque config error: #{message}")
+    end
+  end
+
+  # This request must be approved with a passkey. +reason+ is "policy" when a
+  # phishing-resistant policy requires it (no push was sent), or "step_up" when
+  # the user tapped Approve during a call (Vishing Shield) and the request, still
+  # open, now waits for a passkey in the browser.
+  class PasskeyRequiredError < Error
+    attr_reader :request_id, :reason
+
+    def initialize(request_id, reason = "policy")
+      @request_id = request_id
+      @reason = reason
+      super(if reason == "step_up"
+              "Touchque: request '#{request_id}' must now be approved with a passkey: the user approved on the phone during a call."
+            else
+              "Touchque: request '#{request_id}' must be approved with a passkey (phishing-resistant policy); no push was sent."
+            end)
+    end
+  end
+
+  # An AI agent's approval ended without a usable approval: +status+ is rejected,
+  # blocked, revoked, expired, stale (approved too long ago) or redeemed (already used).
+  class ApprovalError < Error
+    attr_reader :approval_id, :status, :reason
+
+    def initialize(approval_id, status, reason = nil)
+      @approval_id = approval_id
+      @status = status
+      @reason = reason
+      super("Touchque: approval '#{approval_id}' is #{status}#{reason ? " (#{reason})" : ""}.")
+    end
+  end
+
+  # An approval does not say what you are about to execute (another person,
+  # action type, amount, recipient...), or it is not a valid token from Touchque.
+  # Do not execute.
+  class ApprovalMismatchError < Error
+    def initialize(message)
+      super("Touchque: #{message}")
+    end
+  end
+
+  # McpAuth refused a request: answer with +status+ (401, 403) and the
+  # WWW-Authenticate header in +www_authenticate+. +error+ is missing_token,
+  # invalid_token, invalid_dpop_proof or insufficient_scope.
+  class McpAuthError < Error
+    attr_reader :status, :error, :www_authenticate
+
+    def initialize(status, error, message, www_authenticate)
+      @status = status
+      @error = error
+      @www_authenticate = www_authenticate
+      super(message)
+    end
+  end
+
+  # A Touchque Login sign-in or token check failed; +error_code+ is machine-readable.
+  class HostedLoginError < Error
+    attr_reader :error_code, :description, :status
+
+    def initialize(error_code, description = nil, status = nil)
+      @error_code = error_code
+      @description = description
+      @status = status
+      super(description ? "#{error_code}: #{description}" : error_code)
+    end
+  end
+
+  # A My Account API call failed; step_up? means the sign-in is too old for it (RFC 9470).
+  class MyAccountError < Error
+    attr_reader :error_code, :status, :description, :max_age
+
+    def initialize(error_code, status, description = nil, max_age = nil)
+      @error_code = error_code
+      @status = status
+      @description = description
+      @max_age = max_age
+      super(description ? "#{error_code}: #{description}" : error_code)
+    end
+
+    # True when the person must sign in again (authorization_url with max_age: 0) before this change.
+    def step_up?
+      error_code == "insufficient_user_authentication"
+    end
+  end
+end

data/lib/touchque/flow.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+module Touchque
+  # The headless step-up flow shared by every integration: start → show the step in
+  # YOUR UI → check → complete exactly once. A "step" is a plain Hash, safe to send to
+  # the browser as JSON: state (waiting | approved | rejected | expired | enroll |
+  # passkey_required | offline | blocked | frozen | rate_limited) and whatever the user
+  # has to see (the matching number, the enrollment QR, the offline QR). No secrets.
+  module Steps
+    STATE_MAP = { "PENDING" => "waiting", "CONFIRMED" => "approved", "REJECTED" => "rejected", "EXPIRED" => "expired" }.freeze
+
+    module_function
+
+    # Starts an approval for +action+; never waits.
+    def start(client, action, user, details: nil, reference_id: nil, ip: nil, user_agent: nil, enroll: true, browser_proof: nil, context: nil)
+      raise ConfigError, "start() needs the user id" if user.to_s.empty?
+
+      norm = Details.normalize(details)
+      norm = nil if norm.empty?
+      begin
+        res = client.login.request(user, type: action, reference_id: reference_id, client_ip: ip, user_agent: user_agent,
+                                         details: norm, browser_proof: browser_proof, context: context)
+        canary = res.dig("canary", "url").is_a?(String) ? { "url" => res.dig("canary", "url") } : nil
+        if res["requiresPasskey"]
+          step = { "state" => "passkey_required", "requestId" => res["requestId"], "expiresAt" => res["expiresAt"], "details" => norm }.merge(why(res))
+          step["canary"] = canary if canary
+          return step
+        end
+        step = { "state" => "waiting", "requestId" => res["requestId"], "number" => res["challengeCode"],
+                 "expiresAt" => res["expiresAt"], "details" => norm }.merge(why(res))
+        # Only when the workspace collects behavioural signals.
+        step["telemetryToken"] = res["telemetryToken"] if res["telemetryToken"] && !res["telemetryToken"].empty?
+        # Mirror Alarm: the page showing this first step loads the canary.
+        step["canary"] = canary if canary
+        step
+      rescue APIError => e
+        code = e.code || e.error
+        why = e.case_code ? { "caseCode" => e.case_code } : {}
+        if e.status == 404 && (code == "device_not_linked" || e.message.downcase.include?("linked device"))
+          return enroll ? enroll_step(client, user) : { "state" => "enroll" }
+        end
+        return { "state" => "frozen", "retryAfter" => e.retry_after }.merge(why) if e.status == 423
+        return { "state" => "rate_limited", "retryAfter" => e.retry_after }.merge(why) if e.status == 429
+        if e.status == 400 && (code == "unknown_action" || e.message.downcase.include?("invalid action type"))
+          raise ConfigError, "Unknown action \"#{action}\". Create it once with client.action_types.define(\"#{action}\") or in the dashboard (Action Types)."
+        end
+        if e.status == 403
+          reason = (code == "blocked" ? e.reason : nil) ||
+                   (code == "passkey_not_registered" || e.error == "phishing_resistant_required" ? "passkey_not_registered" : nil) ||
+                   (code == "action_disabled" ? "action_disabled" : nil) || code || "blocked"
+          return { "state" => "blocked", "reason" => reason }.merge(why)
+        end
+        raise
+      end
+    end
+
+    # First-time linking. Never unlinks a phone: a secret is only re-issued when the
+    # account is confirmed NOT linked.
+    def enroll_step(client, user)
+      gen = client.auth.generate_secret(user)
+      { "state" => "enroll", "enroll" => gen.slice("qrCodeDataUrl", "recoveryCodes", "expiresAt") }
+    rescue APIError => e
+      raise unless e.status == 409
+
+      current = begin
+        client.auth.get_user(user)
+      rescue APIError
+        nil
+      end
+      return { "state" => "enroll", "reason" => "already_linked" } if current && (current["used"] || current["deviceId"])
+
+      reset = client.auth.reset_secret(user)
+      { "state" => "enroll", "enroll" => reset.slice("qrCodeDataUrl", "recoveryCodes", "expiresAt") }
+    end
+
+    # "Why?": the case code and plain reasons of a login request's answer, for its step.
+    def why(res)
+      out = {}
+      out["caseCode"] = res["caseCode"] if res["caseCode"].is_a?(String) && !res["caseCode"].empty?
+      reasons = (res["reasons"].is_a?(Array) ? res["reasons"] : []).filter_map do |r|
+        { "code" => r["code"], "text" => r["text"].is_a?(String) ? r["text"] : "" } if r.is_a?(Hash) && r["code"].is_a?(String)
+      end
+      out["reasons"] = reasons unless reasons.empty?
+      out
+    end
+
+    # Where a started approval is now.
+    def check(client, request_id)
+      s = client.login.status(request_id)
+      state = s["status"] == "PENDING" && s["requiresPasskey"] ? "passkey_required" : STATE_MAP.fetch(s["status"], "waiting")
+      step = { "state" => state, "requestId" => request_id }
+      step["assurance"] = s["assurance"] if state == "approved" && s["assurance"]
+      step
+    end
+
+    # Uses an approved request exactly once and checks it is for THIS user, action and
+    # transaction. ApprovalMismatchError when it is for something else.
+    def complete(client, request_id, user, action, details: nil, reference_id: nil)
+      res = client.login.consume(request_id)
+      same_user = res["externalUsername"].to_s.downcase == user.to_s.downcase
+      same_details = Details.digest(details) == Details.digest(res["details"])
+      # No reference and an empty one are the same: the API answers null for both.
+      same_ref = (res["referenceId"].to_s.empty? ? nil : res["referenceId"]) == (reference_id.to_s.empty? ? nil : reference_id)
+      if !same_user || res["type"] != action || !same_details || !same_ref
+        raise ApprovalMismatchError, "this approval is for a different user, action or transaction."
+      end
+
+      approval = {
+        "requestId" => request_id, "user" => res["externalUsername"], "action" => res["type"],
+        "assurance" => res["assurance"], "confirmedVia" => res["confirmedVia"], "approvalProof" => res["approvalProof"]
+      }
+      if res.key?("provisional")
+        # Vishing Shield: approved during a call. Treat the session as limited: critical actions are
+        # refused until APPROVAL_RECONFIRMED, and APPROVAL_REVOKED means end it.
+        approval.merge!("provisional" => res["provisional"] ? true : false, "revoked" => res["revoked"] ? true : false,
+                        "revokeReason" => res["revokeReason"], "reconfirmedAt" => res["reconfirmedAt"])
+      end
+      approval
+    end
+
+    # The browser echoes this token back while it waits. Signed with a key derived from
+    # the API secret, it binds the approval to one user, action and transaction.
+    def sign_guard_token(api_secret, claims)
+      body = Util.b64url(Util.json(claims))
+      "v1.#{body}.#{Util.b64url(Util.hmac(token_key(api_secret), body))}"
+    end
+
+    def verify_guard_token(api_secret, token)
+      return nil if token.nil? || token.empty? || token.length > 4096
+
+      parts = token.split(".", -1)
+      return nil unless parts.length == 3 && parts[0] == "v1"
+      return nil unless Util.secure_compare(Util.b64url(Util.hmac(token_key(api_secret), parts[1])), parts[2])
+
+      claims = Util.parse_json(Util.b64url_decode(parts[1]).force_encoding("UTF-8"))
+      return nil unless claims.is_a?(Hash) && claims["exp"].is_a?(Numeric) && claims["exp"] >= Util.now_ms
+
+      claims
+    rescue ArgumentError
+      nil
+    end
+
+    def token_key(api_secret)
+      Util.hmac(api_secret, "touchque-guard-token-v1")
+    end
+  end
+
+  # Framework-agnostic step-up guard (the Rails concern is a thin wrapper over it).
+  # Contract, the same in every Touchque server SDK:
+  #   1st request            -> 202 {"touchque" => step, "token" => ...}  show the step in your UI
+  #   repeat with the token   -> 202 while waiting, then the protected action runs once
+  #   refused                 -> 403 / 408 / 423 / 429 {"touchque" => {"state" => ...}}
+  # Request headers the browser sends back: X-Touchque-Token, X-Touchque-Offline: 1,
+  # X-Touchque-Code (+ X-Touchque-Code-Type: totp), X-Touchque-Browser (silent sign-ins).
+  module Guard
+    TOKEN_HEADER = "X-Touchque-Token"
+    OFFLINE_HEADER = "X-Touchque-Offline"
+    CODE_HEADER = "X-Touchque-Code"
+    CODE_TYPE_HEADER = "X-Touchque-Code-Type"
+    BROWSER_HEADER = "X-Touchque-Browser"
+
+    TOKEN_TTL_MS = 10 * 60 * 1000
+    MAX_BROWSER_PROOF = 4096
+    STATUS = { "waiting" => 202, "enroll" => 202, "passkey_required" => 202, "offline" => 202, "approved" => 200,
+               "rejected" => 403, "blocked" => 403, "expired" => 408, "frozen" => 423, "rate_limited" => 429 }.freeze
+    WAITING = %w[waiting passkey_required offline].freeze
+
+    module_function
+
+    # The guard headers from a header getter (name => value or nil).
+    def input_from_headers(get)
+      {
+        token: presence(get.call(TOKEN_HEADER)),
+        offline: %w[1 true].include?(get.call(OFFLINE_HEADER)),
+        code: presence(get.call(CODE_HEADER)),
+        code_type: presence(get.call(CODE_TYPE_HEADER))
+      }
+    end
+
+    # +silent_sign_in+: false/nil (default), true, or { max_age_seconds: Integer >= 0 }.
+    def assert_silent_sign_in!(option, who)
+      return if option.nil? || option == true || option == false
+
+      if option.is_a?(Hash) && (option.keys.map(&:to_s) - ["max_age_seconds"]).empty?
+        max = option[:max_age_seconds] || option["max_age_seconds"]
+        return if max.nil? || (max.is_a?(Integer) && max >= 0)
+      end
+      raise ArgumentError, "#{who}: silent_sign_in must be true, false or { max_age_seconds: Integer >= 0 }."
+    end
+
+    def silent_on?(option)
+      option == true || option.is_a?(Hash)
+    end
+
+    # True when this request only polls an approval already on its way: a valid token
+    # bound to this user/action/details, still waiting, and no offline switch or code.
+    def status_poll?(client, user, action, details: nil, reference_id: nil, token: nil, offline: false, code: nil)
+      return false if user.to_s.empty? || token.to_s.empty? || offline || !code.to_s.empty?
+
+      claims = Steps.verify_guard_token(client.api_secret, token)
+      return false unless claims && claims["rid"]
+
+      bound?(claims, user, action, details, reference_id) && WAITING.include?(claims["st"])
+    end
+
+    def bound?(claims, user, action, details, reference_id)
+      claims["u"] == user && claims["a"] == action && claims["d"] == Details.digest(details) && claims["r"] == reference_id
+    end
+
+    # Runs one step of the guard: {status: 200, approved: approval} (run your protected
+    # action once) or {status:, body: {"touchque" => step, "token" => ...}} to send back.
+    # Silent sign-ins: with +silent_sign_in+ on, a new attempt that carries a browser
+    # proof first asks Touchque (risk.check); only an answer of exactly prompt: false
+    # approves at once with no push. Otherwise, and on any error, the usual push starts.
+    def run(client, user, action, details: nil, reference_id: nil, ip: nil, user_agent: nil, token: nil, offline: false,
+            code: nil, code_type: nil, enroll: true, browser_proof: nil, silent_sign_in: false, context: nil)
+      if user.to_s.empty?
+        return error(401, { "state" => "blocked", "reason" => "unauthenticated" }, "unauthenticated", "Sign in first.")
+      end
+
+      norm = Details.normalize(details)
+      norm = nil if norm.empty?
+      base = { "u" => user, "a" => action, "d" => Details.digest(details), "r" => reference_id }
+      secret = client.api_secret
+      issue = lambda do |step, extra = {}|
+        step = step.merge("details" => norm) if norm && step["details"].nil? && step["state"] != "blocked"
+        claims = base.merge("st" => step["state"], "rid" => step["requestId"], "n" => step["number"],
+                            "oc" => step.dig("offline", "challengeId"), "exp" => Util.now_ms + TOKEN_TTL_MS)
+        claims["cc"] = step["caseCode"] if step["caseCode"]
+        claims.merge!(extra)
+        { status: STATUS.fetch(step["state"]), body: { "touchque" => step.compact, "token" => Steps.sign_guard_token(secret, claims) } }
+      end
+
+      begin
+        claims = Steps.verify_guard_token(secret, token)
+        bound = claims && bound?(claims, user, action, details, reference_id) ? claims : nil
+        rid = bound && bound["rid"]
+        n = bound && bound["n"]
+        oc = bound && bound["oc"]
+        st = bound && bound["st"]
+        keep = { "oc" => oc, "rid" => rid, "n" => n }
+
+        # Offline: the user typed the code from the phone.
+        if bound && !code.to_s.empty? && (st == "offline" || code_type == "totp")
+          totp = code_type == "totp"
+          res = totp ? client.offline.verify_totp(user, code, type: action, client_ip: ip, request_id: rid) : client.offline.verify(oc.to_s, code)
+          for_this = (res["externalUsername"].to_s.empty? || res["externalUsername"].downcase == user.downcase) &&
+                     (res["type"].to_s.empty? || res["type"] == action)
+          if res["approved"] && for_this
+            return { status: 200, approved: {
+              "requestId" => oc || "offline-totp", "user" => user, "action" => action,
+              "assurance" => { "phishingResistant" => false, "method" => totp ? "offline_totp" : "offline_code" },
+              "confirmedVia" => totp ? "OFFLINE_TOTP" : "OFFLINE_CODE", "approvalProof" => nil
+            } }
+          end
+          if res["reason"] == "invalid_code" && !totp
+            return issue.call({ "state" => "offline", "offline" => { "challengeId" => oc.to_s, "attemptsLeft" => res["attemptsLeft"] } }, keep)
+          end
+          return issue.call({ "state" => "offline", "reason" => "invalid_code" }, keep) if res["reason"] == "invalid_code"
+          # The phone rejected the push this QR belongs to: the whole sign-in is over.
+          return issue.call({ "state" => "rejected", "requestId" => rid, "reason" => "request_rejected" }) if res["reason"] == "request_rejected"
+          # The push now waits for a passkey (Vishing Shield): no code may finish it.
+          if res["reason"] == "passkey_required" && rid
+            return issue.call({ "state" => "passkey_required", "requestId" => rid, "number" => n }, { "n" => n })
+          end
+
+          return issue.call({ "state" => res["reason"] == "expired" ? "expired" : "blocked", "reason" => res["reason"] || "offline_failed" })
+        end
+
+        if offline
+          begin
+            # Tie the QR to the push it follows: a phone-side rejection kills it; number matching carries over.
+            ch = client.offline.challenge(user, type: action, details: norm, client_ip: ip, user_agent: user_agent, request_id: rid)
+            offline_step = ch.slice("challengeId", "qrDataUrl", "expiresAt", "totpAvailable")
+            offline_step["challengeCode"] = ch["challengeCode"] if ch["challengeCode"] && !ch["challengeCode"].empty?
+            return issue.call({ "state" => "offline", "offline" => offline_step }, { "rid" => rid, "n" => ch["challengeCode"] || n })
+          rescue APIError => e
+            err = e.code || e.error
+            return issue.call({ "state" => "rejected", "requestId" => rid, "reason" => "request_rejected" }) if e.status == 409 && err == "request_rejected"
+            if rid && err == "passkey_required"
+              return issue.call({ "state" => "passkey_required", "requestId" => rid, "number" => n }, { "n" => n })
+            end
+            return issue.call({ "state" => "blocked", "reason" => e.code || e.error || "offline_unavailable" }) if e.status < 500
+
+            raise
+          end
+        end
+
+        # Waiting on a push / passkey, or the offline QR next to a push still open: poll, run once approved.
+        if bound && rid && WAITING.include?(st)
+          now = Steps.check(client, rid)
+          if now["state"] == "approved"
+            begin
+              return { status: 200, approved: Steps.complete(client, rid, user, action, details: details, reference_id: reference_id) }
+            rescue APIError => e
+              raise unless e.status == 409
+
+              return issue.call({ "state" => "expired", "reason" => e.code || "already_used" })
+            end
+          end
+          # The push behind the QR moved to a passkey after a tap during a call.
+          if st == "offline" && now["state"] == "passkey_required"
+            return issue.call({ "state" => "passkey_required", "requestId" => rid, "number" => n }, { "n" => n })
+          end
+          # Nothing changed for the user: keep showing the QR they have.
+          return issue.call({ "state" => "offline", "offline" => { "challengeId" => oc.to_s } }, keep) if st == "offline" && %w[waiting expired].include?(now["state"])
+          if %w[waiting passkey_required].include?(now["state"])
+            waiting = { "state" => now["state"], "requestId" => rid, "number" => n }
+            # "Why?": the case code stays on screen while it waits.
+            waiting["caseCode"] = bound["cc"] if bound["cc"]
+            return issue.call(waiting, { "n" => n })
+          end
+          return issue.call({ "state" => now["state"], "requestId" => rid })
+        end
+
+        # Anything else (no or foreign token, enrollment finished, new attempt): start.
+        proof = browser_proof.is_a?(String) && !browser_proof.empty? && browser_proof.length <= MAX_BROWSER_PROOF ? browser_proof : nil
+        if proof && silent_on?(silent_sign_in)
+          silent = silent_approval(client, user, action, proof, ip, user_agent, silent_sign_in, context)
+          return { status: 200, approved: silent } if silent
+        end
+        issue.call(Steps.start(client, action, user, details: norm, reference_id: reference_id, ip: ip, user_agent: user_agent,
+                                                     enroll: enroll, browser_proof: proof, context: context))
+      rescue ConfigError => e
+        Touchque.log :error, "[Touchque] #{e.message}"
+        error(500, { "state" => "blocked", "reason" => "misconfigured" }, "misconfigured", "Two-factor approval is not configured correctly.")
+      rescue StandardError => e
+        # Anything else (Touchque unreachable, an approval for another transaction, a bug)
+        # fails closed with the contract's 503, never a bare 500.
+        Touchque.log :error, "[Touchque] approval failed: #{e.class}: #{e.message}"
+        error(503, { "state" => "blocked", "reason" => "unavailable" }, "unavailable", "Two-factor approval is temporarily unavailable.")
+      end
+    end
+
+    def error(status, step, code, message)
+      { status: status, body: { "touchque" => step, "error" => { "code" => code, "message" => message } } }
+    end
+
+    # Fails closed: only an answer of exactly prompt: false approves.
+    def silent_approval(client, user, action, proof, ip, user_agent, option, context)
+      max_age = option.is_a?(Hash) ? (option[:max_age_seconds] || option["max_age_seconds"]) : nil
+      res = client.risk.check(user, type: action, client_ip: ip, user_agent: user_agent, browser_proof: proof,
+                                    max_age_seconds: max_age, context: context)
+      return nil unless res["prompt"] == false
+
+      {
+        "requestId" => "silent", "user" => user, "action" => action,
+        "assurance" => { "phishingResistant" => false, "method" => "silent" },
+        "confirmedVia" => "SILENT", "approvalProof" => nil,
+        # Nothing was sent to the phone; why Touchque let this known browser in.
+        "reasons" => res["reasons"]
+      }
+    rescue StandardError => e
+      Touchque.log :warn, "[Touchque] silent sign-in check failed, asking the phone: #{e.class}: #{e.message}"
+      nil
+    end
+
+    def presence(value)
+      value.nil? || value.to_s.empty? ? nil : value.to_s
+    end
+  end
+end