touchque 5.0.0

data/lib/touchque/resources/mobile.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Touchque Mobile SDK, your backend's side: your own iOS/Android app is the approver
+    # of your users (white-label); they never install the Touchque app.
+    #
+    # 1. A user signed in to your app turns approvals on: create_enrollment gives a
+    #    one-time token; your app hands it to the SDK (Touchque.enroll).
+    # 2. Ask for approvals as always (login.request, start, the guards).
+    # 3. Without your APNs/FCM keys in update_settings, Touchque sends you a signed
+    #    MOBILE_PUSH webhook per request: verify it, then Mobile.push_from_webhook gives
+    #    the APNs payload / FCM data to send with your own credentials.
+    class Mobile
+      SETTINGS = {
+        "ios_app_ids" => "iosAppIds", "android_packages" => "androidPackages", "android_certs" => "androidCerts",
+        "attestation" => "attestation", "enroll_ttl_seconds" => "enrollTtlSeconds", "apns" => "apns", "fcm" => "fcm"
+      }.freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # A one-time enrollment token for a user you signed in. Whoever spends it becomes
+      # the user's approver, so authenticate the user first. APIError already_enrolled
+      # (pass replace: true) or account_frozen.
+      def create_enrollment(external_username, replace: false, ttl_seconds: nil)
+        raise ConfigError, "mobile.create_enrollment() needs the user (external_username)" if external_username.to_s.empty?
+
+        body = { "externalUsername" => external_username }
+        body["replace"] = true if replace
+        body["ttlSeconds"] = Integer(ttl_seconds) unless ttl_seconds.nil?
+        @http.post("/mobile/enrollments", body)
+      end
+
+      # The devices inside your app (default: active ones), newest first: {"devices", "nextCursor"}.
+      # status: active, revoked or all.
+      def list_devices(external_username: nil, status: nil, limit: nil, cursor: nil)
+        @http.get("/mobile/devices", Util.compact({ "externalUsername" => external_username, "status" => status, "limit" => limit, "cursor" => cursor }))
+      end
+
+      def get_device(device_id)
+        raise ConfigError, "mobile.get_device() needs the device id" if device_id.to_s.empty?
+
+        @http.get("/mobile/devices/#{Util.seg(device_id)}")["device"]
+      end
+
+      # Stops a device from approving (the user has no approver until you enrol again).
+      def remove_device(device_id)
+        raise ConfigError, "mobile.remove_device() needs the device id" if device_id.to_s.empty?
+
+        @http.delete("/mobile/devices/#{Util.seg(device_id)}")
+      end
+
+      # A harmless push to the device, the way a request would reach it: "via" touchque
+      # (your key for its platform) or webhook (MOBILE_PUSH, kind test); "ok": APNs / FCM took it.
+      def test_push(device_id)
+        raise ConfigError, "mobile.test_push() needs the device id" if device_id.to_s.empty?
+
+        @http.post("/mobile/devices/#{Util.seg(device_id)}/test-push", {})
+      end
+
+      def settings
+        @http.get("/mobile/settings")["settings"]
+      end
+
+      # Which apps may enrol, whether they must prove themselves, and your push keys. Only
+      # the keys given change: ios_app_ids, android_packages, android_certs ({package =>
+      # [SHA-256 of its signing certificate]}), attestation (off | optional | required),
+      # enroll_ttl_seconds, apns ({keyId:, teamId:, topic:, key: the .p8 text, production:}:
+      # Touchque then sends the iOS push itself), fcm ({serviceAccount: the JSON}: the
+      # Android push); nil removes a key. The keys are never shown back.
+      def update_settings(**changes)
+        unknown = changes.keys.map(&:to_s) - SETTINGS.keys
+        raise ConfigError, "mobile.update_settings(): unknown setting #{unknown.join(", ")}" unless unknown.empty?
+
+        @http.put("/mobile/settings", changes.to_h { |k, v| [SETTINGS[k.to_s], v] })["settings"]
+      end
+
+      # The push to send for a verified MOBILE_PUSH webhook, or nil for any other event:
+      # deviceId, externalUsername, platform, pushToken (nil: send by your own user → device
+      # mapping), requestId, expiresAt, kind, alert (English, translate it), apns (the APNs
+      # payload: alert + the custom key "touchque") and fcmData. No secret, no details, no number.
+      def self.push_from_webhook(event)
+        event = Util.stringify(event) if event
+        return nil unless event.is_a?(Hash) && event["event"] == "MOBILE_PUSH"
+
+        data = event["data"].is_a?(Hash) ? event["data"] : {}
+        touchque = data["touchque"].is_a?(String) ? data["touchque"] : Util.json(data["touchque"] || {})
+        alert = event["alert"]
+        aps = { "sound" => "default", "interruption-level" => "time-sensitive" }
+        aps["alert"] = alert if alert
+        {
+          "deviceId" => event["deviceId"],
+          "externalUsername" => event["externalUsername"],
+          "platform" => event["platform"] == "android" ? "android" : "ios",
+          "pushToken" => event["pushToken"].is_a?(String) ? event["pushToken"] : nil,
+          "requestId" => event["requestId"],
+          "expiresAt" => event["expiresAt"],
+          # test: a test push sent from the dashboard
+          "kind" => %w[notice test].include?(event["kind"]) ? event["kind"] : "approval",
+          "alert" => alert,
+          "apns" => { "aps" => aps, "touchque" => touchque },
+          "fcmData" => { "touchque" => touchque }
+        }
+      end
+
+      # True once a push is past its request's expiry (don't send it any more).
+      def self.push_expired?(push, now = Time.now)
+        at = Util.parse_time(push["expiresAt"])
+        !at.nil? && at <= now.to_f
+      end
+    end
+  end
+end

data/lib/touchque/resources/people.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Silent sign-ins: ask Touchque's risk engine whether a sign-in needs the phone at
+    # all, and manage the browsers it knows for a user. A browser becomes known when the
+    # user approves a request that carried its device-bound key proof; later +check+ with
+    # a fresh proof from the same browser answers "prompt" => false when nothing about
+    # the sign-in is new. Nothing goes to the phone.
+    class Risk
+      ASSURANCE = %w[high normal low].freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Reads a POST /risk/check answer, failing closed: "prompt" is false ONLY when the
+      # answer says exactly prompt: false. Malformed reasons become [], an unknown or
+      # missing assurance is "normal".
+      def self.parse_check(raw)
+        body = raw.is_a?(Hash) ? raw : {}
+        reasons = (body["reasons"].is_a?(Array) ? body["reasons"] : []).filter_map do |r|
+          next unless r.is_a?(Hash) && r["code"].is_a?(String)
+
+          { "code" => r["code"], "text" => r["text"].is_a?(String) ? r["text"] : "" }
+        end
+        out = {
+          "prompt" => !(body.key?("prompt") && body["prompt"] == false),
+          "reasons" => reasons,
+          "assurance" => ASSURANCE.include?(body["assurance"]) ? body["assurance"] : "normal",
+          "silentMode" => body["silentMode"] == "shadow" ? "shadow" : "enforce"
+        }
+        # "Why?": the check's case code, to show the user.
+        out["caseCode"] = body["caseCode"] if body["caseCode"].is_a?(String)
+        out
+      end
+
+      # Should this sign-in ask the phone? Skip the push only when "prompt" is false;
+      # on any error, ask as usual. A critical action always asks.
+      # max_age_seconds: your own limit on how long ago the last phone approval in this
+      # browser may be (0 = always ask). context: for your Touchque Actions only.
+      # device_risk_request_id: the page's identification (deviceRisk.identify), or device_risk:
+      # the page's report (deviceRisk.collect); a device signal is never silent.
+      def check(external_username, type: nil, client_ip: nil, user_agent: nil, browser_proof: nil,
+                client_signals: nil, max_age_seconds: nil, context: nil, device_risk: nil, device_risk_request_id: nil)
+        raise ConfigError, "risk.check() needs the user (external_username)" if external_username.to_s.empty?
+        if !max_age_seconds.nil? && (!max_age_seconds.is_a?(Integer) || max_age_seconds.negative?)
+          raise ConfigError, "risk.check(): max_age_seconds must be an integer >= 0 (0 = always ask)"
+        end
+
+        body = { "externalUsername" => external_username }
+        { "type" => type, "clientIp" => client_ip, "userAgent" => user_agent, "browserProof" => browser_proof,
+          "clientSignals" => client_signals, "deviceRisk" => device_risk,
+          "deviceRiskRequestId" => device_risk_request_id }.each { |k, v| body[k] = v if v.is_a?(String) && !v.empty? }
+        body["maxAgeSeconds"] = max_age_seconds unless max_age_seconds.nil?
+        body["context"] = Util.stringify(context) if context.is_a?(Hash) && !context.empty?
+        self.class.parse_check(@http.post("/risk/check", body))
+      end
+
+      # The browsers Touchque knows for a user: {"browsers" => [...]}.
+      def browsers(external_username)
+        raise ConfigError, "risk.browsers() needs the user (external_username)" if external_username.to_s.empty?
+
+        res = @http.get("/risk/browsers", { "externalUsername" => external_username })
+        { "browsers" => res["browsers"].is_a?(Array) ? res["browsers"] : [] }
+      end
+
+      # Forgets one browser (+thumbprint+) or all of a user's browsers: {"forgotten" => n}.
+      def forget_browsers(external_username, thumbprint: nil)
+        raise ConfigError, "risk.forget_browsers() needs the user (external_username)" if external_username.to_s.empty?
+
+        @http.post("/risk/browsers/forget", Util.compact({ "externalUsername" => external_username, "thumbprint" => thumbprint }))
+      end
+    end
+
+    # Never Locked Out: move a user whose phone is lost, dead or replaced to a new phone
+    # without a help desk. Users name colleagues who vouch for them (set_vouchers, behind
+    # an approval on their phone); when the phone is gone, after the password: start (show
+    # "bindUri" as a QR for the Touchque app on the new phone), poll status and show each
+    # voucher's "code"; after a cooling-off nobody vetoed the account is on the new phone.
+    class Recovery
+      OPEN_STATUSES = %w[AWAITING_DEVICE VOUCHING COOLING].freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Still waiting for the new phone, the vouchers or the cooling-off.
+      def self.open?(recovery)
+        OPEN_STATUSES.include?(recovery.is_a?(Hash) ? recovery["status"] : nil)
+      end
+
+      def vouchers(external_username)
+        require!("vouchers", "external_username", external_username)
+        @http.get("/recovery/vouchers", { "externalUsername" => external_username })
+      end
+
+      # Replaces the user's vouchers (at most 5 are kept). Ask for the user's phone first.
+      def set_vouchers(external_username, vouchers)
+        require!("set_vouchers", "external_username", external_username)
+        raise ConfigError, "recovery.set_vouchers(): every voucher must be a string" unless vouchers.all?(String)
+
+        @http.post("/recovery/vouchers", { "externalUsername" => external_username, "vouchers" => vouchers.to_a })
+      end
+
+      # Starts moving the user to a new phone. Call it only after the first factor. APIError
+      # with code not_enough_vouchers, recovery_in_progress, blocked, frozen or rate_limited.
+      def start(external_username, client_ip: nil, user_agent: nil, display_name: nil, fallback_vouchers: nil,
+                required: nil, cool_off_minutes: nil, details: nil, notice_details: nil)
+        require!("start", "the user (external_username)", external_username)
+        { "required" => required, "cool_off_minutes" => cool_off_minutes }.each do |name, v|
+          next if v.nil?
+          raise ConfigError, "recovery.start(): #{name} must be a positive integer" unless v.is_a?(Integer) && v.positive?
+        end
+        body = { "externalUsername" => external_username }
+        body.merge!(Util.compact({ "clientIp" => client_ip, "userAgent" => user_agent, "displayName" => display_name }))
+        body["fallbackVouchers"] = fallback_vouchers.to_a if fallback_vouchers && !fallback_vouchers.empty?
+        body["required"] = required unless required.nil?
+        body["coolOffMinutes"] = cool_off_minutes unless cool_off_minutes.nil?
+        body["details"] = Util.stringify(details) if details && !details.empty?
+        body["noticeDetails"] = Util.stringify(notice_details) if notice_details && !notice_details.empty?
+        @http.post("/recovery/start", body)
+      end
+
+      # The recovery now, with its receipt chain. Poll it while the user waits.
+      def status(recovery_id)
+        require!("status", "recovery_id", recovery_id)
+        @http.get("/recovery/#{Util.seg(recovery_id)}")
+      end
+
+      # A user's recoveries, or (open: true) every running one of your workspace.
+      def list(external_username: nil, open: false)
+        if external_username.to_s.empty? && !open
+          raise ConfigError, "recovery.list() needs external_username or open: true"
+        end
+
+        res = @http.get("/recovery", { "externalUsername" => external_username.to_s.empty? ? nil : external_username, "open" => open ? "true" : nil })
+        res["recoveries"].is_a?(Array) ? res["recoveries"] : []
+      end
+
+      # Stops a running recovery (e.g. an admin who does not believe it). Does not freeze the user.
+      def veto(recovery_id, by: nil, reason: nil)
+        require!("veto", "recovery_id", recovery_id)
+        @http.post("/recovery/#{Util.seg(recovery_id)}/veto", Util.compact({ "by" => by, "reason" => reason }))
+      end
+
+      private
+
+      def require!(method, what, value)
+        raise ConfigError, "recovery.#{method}() needs #{what}" if value.to_s.empty?
+      end
+    end
+
+    # Help desk: IT working on a person's account in the open. open before your help desk
+    # acts on someone's account (their phone gets a calm notice); verify before a sensitive
+    # action (a 2-digit "challengeCode" the agent reads to the person, who types it and
+    # approves on their phone); spend right before the action. No phone (code no_phone,
+    # route never_locked_out): the person moves to a new phone with Never Locked Out.
+    class Assist
+      def initialize(http)
+        @http = http
+      end
+
+      # The check of +request_id+ passed on the person's phone and was not used yet.
+      def self.check_passed?(session, request_id)
+        check = (session["checks"] || []).find { |c| c["requestId"] == request_id }
+        !check.nil? && check["outcome"] == "verified" && check["spentAt"].nil?
+      end
+
+      # Starts helping a person: agent is {name:, title:, ref: your id for the agent}.
+      # A session of the same agent for the same person is replaced.
+      def open(external_username, agent:, reason: nil, ttl_minutes: nil, notify: true)
+        agent = Util.stringify(agent || {})
+        if external_username.to_s.empty? || agent["name"].to_s.empty?
+          raise ConfigError, "assist.open() needs external_username and agent name"
+        end
+
+        body = { "externalUsername" => external_username, "agent" => Util.compact(agent) }
+        body["reason"] = reason unless reason.nil?
+        body["ttlMinutes"] = ttl_minutes unless ttl_minutes.nil?
+        body["notify"] = false unless notify
+        @http.post("/assist", body)
+      end
+
+      # The session and its checks. Poll it while a check is pending.
+      def get(id)
+        require!("get", "the session id", id)
+        @http.get(path(id))
+      end
+
+      # A person's sessions, or every open one, newest first.
+      def list(external_username: nil, open: false)
+        raise ConfigError, "assist.list() needs external_username or open: true" if external_username.to_s.empty? && !open
+
+        @http.get("/assist", { "externalUsername" => external_username.to_s.empty? ? nil : external_username, "open" => open ? "true" : nil })["sessions"] || []
+      end
+
+      # Asks the person's phone to confirm +action+ (reset_2fa, reset_password,
+      # activation_link, recovery_link, unlock, new_phone, remove_passkey or your own).
+      def verify(id, action, action_text: nil, details: nil)
+        require!("verify", "the session id and an action", id, action)
+        body = { "action" => action }
+        body["actionText"] = action_text if action_text && !action_text.empty?
+        body["details"] = Util.stringify(details) if details && !details.empty?
+        @http.post(path(id, "/verify"), body)
+      end
+
+      # Uses a passed check for its action, right before you take it; check_required (428) otherwise.
+      def spend(id, request_id, action)
+        require!("spend", "the session id, request_id and action", id, request_id, action)
+        @http.post(path(id, "/spend"), { "requestId" => request_id, "action" => action })
+      end
+
+      # Lifts the person's approval freeze with a passed check for "unlock".
+      def unfreeze(id, request_id)
+        require!("unfreeze", "the session id and request_id", id, request_id)
+        @http.post(path(id, "/unfreeze"), { "requestId" => request_id })
+      end
+
+      # Stops helping; checks still waiting on the phone expire.
+      def end(id, by: nil, reason: nil)
+        require!("end", "the session id", id)
+        @http.post(path(id, "/end"), Util.compact({ "by" => by, "reason" => reason }))
+      end
+
+      private
+
+      def path(id, rest = "")
+        "/assist/#{Util.seg(id)}#{rest}"
+      end
+
+      def require!(method, what, *values)
+        raise ConfigError, "assist.#{method}() needs #{what}" if values.any? { |v| v.to_s.empty? }
+      end
+    end
+  end
+end

data/lib/touchque/resources/qr_pairings.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Pairing a browser by QR code: your page shows a QR code, the person scans it with
+    # the Touchque app, and the phone that scanned is the one asked to approve.
+    #
+    # 1. Your page gets the thumbprint of its browser key (@touchque/web
+    #    browserKey.thumbprint()) and sends it to your server.
+    # 2. create(key_thumbprint, client_ip:, user_agent:) registers a pairing and returns
+    #    "uri" (touchque://pair-browser?...): show it as a QR code. It can be scanned once,
+    #    for ttl_seconds (default 120). The nonce in it never leaves your server and the
+    #    QR: Touchque keeps only its hash.
+    # 3. Poll get(pairing_id): "scanned" once a phone holding one of your users' accounts
+    #    read it ("externalUsername", "proximity"), "confirmed" once the person went on,
+    #    "reported" when they said someone told them to scan it (their 2FA freezes).
+    # 4. login.request(user, qr_pairing: pairing_id) asks that phone, once, with number
+    #    matching; the browser key's fingerprint is one of the rows the phone signs. When
+    #    your own checks say no, refuse(pairing_id, reason:, message:) and the phone
+    #    shows why.
+    class QrPairings
+      # What refuse may tell the phone.
+      REFUSAL_REASONS = %w[policy device_not_approved too_many_browsers rate_limited no_account other].freeze
+
+      B64URL_43 = /\A[A-Za-z0-9_-]{43}\z/
+
+      # What the QR code says: touchque://pair-browser?v=1&p=<pairing>&n=<nonce>&k=<key thumbprint>.
+      def self.uri(pairing_id, nonce, key_thumbprint)
+        "touchque://pair-browser?v=1&p=#{Util.seg(pairing_id)}&n=#{Util.seg(nonce)}&k=#{Util.seg(key_thumbprint)}"
+      end
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Registers a pairing for one browser: {"pairingId", "expiresAt", "nonce", "uri"};
+      # show "uri" as a QR code. +browser+ ("Chrome 155") and +os+ ("macOS 15") are shown
+      # on the phone; +ttl_seconds+ is 30 to 300.
+      def create(key_thumbprint, client_ip: nil, user_agent: nil, browser: nil, os: nil, ttl_seconds: nil)
+        unless key_thumbprint.is_a?(String) && key_thumbprint.match?(B64URL_43)
+          raise ConfigError, "qr_pairings.create needs key_thumbprint: the RFC 7638 thumbprint of the browser key, base64url (43 characters)"
+        end
+        if !ttl_seconds.nil? && !(ttl_seconds.is_a?(Integer) && ttl_seconds.between?(30, 300))
+          raise ConfigError, "qr_pairings.create: ttl_seconds must be 30 to 300"
+        end
+
+        nonce = Util.b64url(SecureRandom.random_bytes(32))
+        body = { "nonceHash" => Util.b64url(Util.sha256(nonce)), "keyThumbprint" => key_thumbprint }
+        { "clientIp" => client_ip, "userAgent" => user_agent, "browser" => browser, "os" => os, "ttlSeconds" => ttl_seconds }.each do |k, v|
+          body[k] = v unless v.nil? || v == ""
+        end
+        created = @http.post("/qr-pairings", body)
+        created.merge("nonce" => nonce, "uri" => self.class.uri(created["pairingId"], nonce, key_thumbprint))
+      end
+
+      # Where a pairing stands; once scanned, who scanned it and how near the phone was.
+      def get(pairing_id)
+        @http.get(path(pairing_id, "get"))
+      end
+
+      # Your own checks refused a scanned pairing; the phone shows +message+. Only a
+      # "scanned" or "confirmed" pairing can be refused (409 not_open otherwise).
+      def refuse(pairing_id, reason:, message:, case_code: nil, device_code: nil)
+        raise ConfigError, "qr_pairings.refuse: reason must be one of #{REFUSAL_REASONS.join(", ")}" unless REFUSAL_REASONS.include?(reason.to_s)
+        raise ConfigError, "qr_pairings.refuse needs message: what the phone shows (up to 300 characters)" if message.to_s.strip.empty?
+
+        body = { "reason" => reason.to_s, "message" => message }
+        body["caseCode"] = case_code unless case_code.to_s.empty?
+        body["deviceCode"] = device_code unless device_code.to_s.empty?
+        @http.post(path(pairing_id, "refuse", "/outcome"), body)
+      end
+
+      private
+
+      def path(pairing_id, method, rest = "")
+        raise ConfigError, "qr_pairings.#{method} needs the pairing id" if pairing_id.to_s.empty?
+
+        "/qr-pairings/#{Util.seg(pairing_id)}#{rest}"
+      end
+    end
+  end
+end

data/lib/touchque/resources/safe_guard.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Safe Guard: a Safe transaction approved on the approver's phone for TouchqueSafeGuard (the
+    # guard on your Safe). You send the raw transaction; the phone gets the raw fields only,
+    # decodes them itself, shows its own rows and signs, with a key only its biometrics unlock, a
+    # 105-byte approval of the hash it computed. Touchque never holds a key that can approve.
+    #
+    # 1. request(user, type, safe_tx) asks the phone (same pipeline as login.request: risk
+    #    engine, push limit, Vishing Shield, case code, always biometrics).
+    # 2. wait_for_approval(request_id) (or poll status) until the phone answered.
+    # 3. Check safeTx["approval"] yourself with Touchque::SafeApproval.verify: it needs your own
+    #    transaction and the approver's key from the guard, not this answer. Pass purpose:
+    #    "schedule" for a governance change; without it only "approve" is accepted.
+    # 4. "purpose" "approve": SafeApproval.with_approvals(owner_signatures, approvals) as the
+    #    signatures of execTransaction. "schedule": send SafeApproval.schedule_call(safe,
+    #    governance_hash, approvals) to the guard; the change runs once its waiting time is over.
+    class SafeGuard
+      NUMBERS = %w[value safeTxGas baseGas gasPrice nonce].freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Asks the approver's phone to approve a Safe transaction. +type+ is an action type from
+      # your dashboard; +safe_tx+ is { "chainId", "safe", "guard", "tx", "config" => { "threshold",
+      # "govThreshold", "govDelay", "exitDelay", "recipientLock" }, "batchTargets", "recipients",
+      # "approverIndex", "locale" }; +expires_in+ is seconds, 30 to 300 (default 300).
+      #
+      #   tq.safe_guard.request("treasurer@acme.com", "safe_payment", {
+      #     "chainId" => 1, "safe" => safe, "guard" => guard,
+      #     "tx" => { "to" => to, "value" => 0, "data" => data, "operation" => 0, "nonce" => 42 },
+      #     "config" => { "threshold" => 2, "govThreshold" => 3, "govDelay" => 172_800, "exitDelay" => 259_200 },
+      #     "approverIndex" => 0
+      #   })
+      def request(external_username, type, safe_tx, reference_id: nil, expires_in: nil, client_ip: nil, user_agent: nil)
+        raise ConfigError, "safe_guard.request needs an external_username" if external_username.to_s.empty?
+        raise ConfigError, "safe_guard.request needs a type: an action type from your dashboard" if type.to_s.empty?
+
+        body = { "externalUsername" => external_username, "type" => type, "safeTx" => wire(safe_tx) }
+        body.merge!(Util.compact({ "referenceId" => reference_id, "expiresIn" => expires_in, "clientIp" => client_ip, "userAgent" => user_agent }))
+        @http.post("/safe-guard/approvals", body)
+      end
+
+      # The request's status and, once approved, the approval (safeTx["approval"], 105 bytes hex).
+      def status(request_id)
+        raise ConfigError, "safe_guard.status needs a request id" if request_id.to_s.empty?
+
+        @http.get("/safe-guard/approvals/#{Util.seg(request_id)}")
+      end
+
+      # Polls until the phone approved and returns the status with the approval. Raises
+      # RejectedError when the person said no, TimeoutError when it expired or +timeout+ seconds
+      # (default 5 minutes, the request's own life) ran out.
+      def wait_for_approval(request_id, timeout: 300, poll_interval: 1.5)
+        deadline = Time.now + timeout
+        loop do
+          s = status(request_id)
+          case s["status"]
+          when "CONFIRMED" then return s
+          when "REJECTED" then raise RejectedError.new(request_id)
+          when "EXPIRED" then raise TimeoutError.new("Touchque: request '#{request_id}' expired before it was approved.", request_id)
+          end
+          raise TimeoutError.new("Touchque: Safe Guard approval '#{request_id}' was not given within #{timeout}s.", request_id) if Time.now > deadline
+
+          sleep poll_interval
+        end
+      end
+
+      private
+
+      # String keys, and large integers as decimal strings, as the API takes them.
+      def wire(safe_tx)
+        raise ConfigError, "safe_guard.request needs safe_tx: { \"chainId\", \"safe\", \"guard\", \"tx\", \"config\", \"approverIndex\" }" unless safe_tx.is_a?(Hash)
+
+        out = safe_tx.transform_keys(&:to_s)
+        tx = out["tx"]
+        raise ConfigError, "safe_guard.request needs safe_tx[\"tx\"]" unless tx.is_a?(Hash)
+
+        out["chainId"] = out["chainId"].to_s if out["chainId"].is_a?(Integer)
+        out["tx"] = tx.transform_keys(&:to_s).to_h { |k, v| [k, NUMBERS.include?(k) && v.is_a?(Integer) ? v.to_s : v] }
+        out
+      end
+    end
+  end
+end