touchque 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6955277b3bc3e32deb8f97a7d137f02f5d3517b7897801a47f2ea7450025459c
-  data.tar.gz: cbbe23f464baba65fc927cd7d34ec609be4bdc1a33d2841e07a53b1f66a0c61c
+  metadata.gz: 8fd0417df799898bf80db545d3ce9d62bc81ea1fb537631ed1e2d869c389e8e6
+  data.tar.gz: ff2565d595c4b7e93c117bf6e414cadb9278d2f739b52a80eec00b0995424bed
 SHA512:
-  metadata.gz: 89047ee9495e0d3f2871feda126bea65fc520db8a4300eb9e49a9c0e167e2a803c34407dbb052101c1104ddc03be71141dfa3bebb818319ebf3058bb74d4370e
-  data.tar.gz: 20ce50cfbc756507d749bc4c404755b74f561708bd7c88f8845d77a4a11115f5df2226b1e2c61a3c324b8f1f908440badc97def0a783567c8a4275d11d776afb
+  metadata.gz: 4bb3567bcc20f35485e45312095b1285c9877e85058bd716ca4409af75e050783177491200fde593d4c06de0e35a7e260072c3bf10afc0a67d6d522392074e76
+  data.tar.gz: 5c38f7c2d6af269aeb6afff09aafd4214d43dd8c001496d9ad541e6f9b734738198e2784285a77fc7644d4520f4e920e5987f2edbb92f154bdc6067f92eb5bd5

data/CHANGELOG.md

@@ -3,7 +3,22 @@
 All notable changes to this project will be documented in this file. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [5.1.0] — 2026-11-12
+
+### Fixed
+- **The first-time QR stays the same while the user scans it.** Every poll with an `enroll` token started again (login request, 404 `device_not_linked`, generate-secret 409, reset), so each 1.5 s poll replaced the QR and the recovery codes on screen and the QR being scanned stopped working. Now:
+  - The enroll step carries `"enroll" => { "expiresAt" }`: the API's `expiresAt` when it is ISO 8601, else now + its `ttlMs`; its token carries that expiry.
+  - A poll with that token reads only the link state (`GET /users/{externalUsername}`). Not linked, with more than 15 s left: 202 `{"touchque":{"state":"enroll","expiresAt":"..."},"token":"..."}` with no `enroll` object, so the page keeps the QR and the recovery codes it shows; no new secret, no push. Linked: the push starts as before. Expired, about to expire, or unknown to Touchque: a new QR comes with `enroll.qrCodeDataUrl`.
+  - `Guard.status_poll?` is true for such a poll while the first-time QR is up (more than 15 s before it expires), so the relay's `POST /login` no longer counts those polls against the per-user limit. Renewing an expiring QR still counts.
+  - Pages on `@touchque/web` need 2.1.0, which keeps the QR it shows for such a step.
+- **A start is always charged.** A first-time QR poll that starts after all (the user linked: the push; the QR expired or is gone: a new QR) calls `Guard.run`'s new `before_start:` first, which may answer instead. The relay's `POST /login` charges it to the username's budget like a new attempt and answers its usual 429 over the limit, so replaying an old enroll token can no longer push on the poll budget.
+- **`require_touchque` answers JSON when `TQ_API_KEY` / `TQ_API_SECRET` are missing.** It raised `Touchque::ConfigError` from `Touchque.client`, so Rails answered its own 500 page. `Touchque.client` is now built inside the guard's error handling on the request, and kept once built. Without keys the action answers 500 `misconfigured` with `Cache-Control: no-store` (401 `unauthenticated` when nobody is signed in) and never runs; it is logged once through `Touchque.logger`: `[Touchque] TQ_API_KEY and TQ_API_SECRET are not set: routes guarded by Touchque answer 500 misconfigured.`
+
+### Added
+- **`error_body:` for `require_touchque`: refusals in your API's own error shape.** `require_touchque "SEND_MONEY", error_body: ->(r) { { message: r[:message], code: r[:code] } }` (a proc run in the controller, or a method name). It is called for every answer of 400 and above (401, 403, 408, 423, 429, 500, 503), never for a 202 step or an approval, with the refusal `{ status:, code:, message:, touchque: }` (a copy of the step). What the result encodes to as JSON decides: a JSON object (a Hash, a Struct or Data, an object with `to_hash` or whose `as_json` is a Hash) is sent with `"touchque"` set to the step (the SDK's key wins, no `token` is added); anything else as it is, as JSON. Status and headers stay the same. One that raises, or a result that cannot be encoded, is logged (`[Touchque] errorBody failed: <message>`) and the default body sent.
+- **Refusal headers.** Every guard answer of 400 and above, from `require_touchque` and the relay, carries `X-Touchque-State` and, when the step has a reason, `X-Touchque-Reason`; `@touchque/web` 2.1.0 reads the step from them when the body has no `touchque` key. Cross-origin pages must expose them (`Access-Control-Expose-Headers`). `Touchque::Guard.headers(result)` gives them, with `Cache-Control` and `Retry-After`, for your own action.
+- `Touchque::Guard.refusal(result)`, and `Touchque::Guard.error_body(result, callable)` for the same shape in your own action (JSON text; the default body, logged, when the callable raises); `Touchque::Guard.default_client` (`Touchque.client`, or `nil` when it cannot be built, logged once), `Touchque::Guard.unauthenticated` and `Touchque::Guard.misconfigured`, the guard's 401 and 500 answers.
+- README: "Guard inside your handler" (`Touchque::Guard.run` after your own checks, what to send back, the 202 and first-time QR polls, `before_start:` for your own rate limits), the `error_body:` option, the refusal headers and what a missing key answers.
 
 ## [5.0.0] — 2026-11-12
 

data/README.md

@@ -17,9 +17,6 @@ Ruby 3.1+, no runtime dependencies beyond the standard library (`net/http`, `ope
 gem "touchque"
 ```
 
-> **Not on RubyGems yet.** Until it is, take it from GitHub:
-> `gem "touchque", git: "https://github.com/Touchque/touchque-ruby"`.
-
 ## Setup
 
 Get an API key and secret from your [Touchque dashboard](https://dashboard.touchque.com):
@@ -67,6 +64,9 @@ again with header `X-Touchque-Token: <token>`; [`@touchque/web`](https://www.npm
 does this loop for you. Once approved the action runs **once**. Refusals answer 403 (rejected,
 blocked), 408 (expired), 423 (frozen) or 429 (rate limited) with `Retry-After`.
 
+A frontend of your own: while the first-time QR is up, polls answer `{"state": "enroll", "expiresAt": ...}`
+without `enroll`, so keep showing the QR you have; a new one comes with `enroll.qrCodeDataUrl`.
+
 The approving user is `current_user`'s email (else id, else username). For your login action
 (nobody is signed in yet) pass `user: -> { session[:password_verified_user] }`.
 
@@ -74,6 +74,51 @@ The approving user is `current_user`'s email (else id, else username). For your
 shown on the phone use `request.remote_ip`: configure `config.action_dispatch.trusted_proxies`
 behind a load balancer.
 
+**A missing key.** `Touchque.client` is built on the first guarded request, inside the guard.
+Without `TQ_API_KEY` / `TQ_API_SECRET` (or `config.touchque`) nothing raises: the action answers
+**500** with `Cache-Control: no-store` and the body
+`{"touchque":{"state":"blocked","reason":"misconfigured"},"error":{"code":"misconfigured","message":"Two-factor approval is not configured correctly."}}`
+(401 `unauthenticated` when nobody is signed in), and never runs. It is logged once, through
+`Touchque.logger`: `[Touchque] TQ_API_KEY and TQ_API_SECRET are not set: routes guarded by Touchque
+answer 500 misconfigured.` A 500 rather than a 503: it is a deploy mistake for your monitoring to
+catch, not an outage to retry. `@touchque/web` shows "Approvals are not set up correctly on this site."
+
+**Refusal headers.** Every answer of 400 and above carries `X-Touchque-State: <state>`, plus
+`X-Touchque-Reason: <reason>` when the step has one; `@touchque/web` 2.1.0 reads the step from them when
+the body has no `touchque` key. A frontend on another origin must list them in
+`Access-Control-Expose-Headers`.
+
+### Your own error shape (`error_body:`)
+
+Refusals (403, 408, 423, 429) answer `{"touchque": step, "token": "..."}`; the guard's own errors (401,
+500, 503) answer `{"touchque": step, "error": {"code", "message"}}`. To answer in your API's own error
+shape, pass `error_body:`:
+
+```ruby
+require_touchque "SEND_MONEY", only: :create,
+                 error_body: ->(r) { { message: r[:message], code: r[:code] } }
+```
+
+It is called for every answer of 400 and above (401, 403, 408, 423, 429, 500, 503), never for a 202
+step or an approval, with the refusal, a Hash:
+
+- `status:`;
+- `code:`: the error's code, else the step's `reason`, else its `state`;
+- `message:`: the error's message, else by state: "The approval was rejected.", "The approval expired.
+  Try again.", "Too many rejected approvals. Try again later." (`frozen`), "Too many attempts. Try again
+  later." (`rate_limited`), "The approval was refused." (anything else);
+- `touchque:`: the step as it would be sent.
+
+The proc runs in the controller (`request` and `t(...)` work there), or name a method:
+`error_body: :touchque_error`. What the result encodes to as JSON decides. A JSON object (a Hash, a
+Struct or Data, an object with `to_hash` or whose `as_json` is a Hash) is sent with `"touchque"` set to
+the step, replacing yours, so `@touchque/web` still sees the state: 403
+`{"message":"The approval was rejected.","code":"rejected","touchque":{"state":"rejected",...}}`. No
+`token` is added. Anything else (a String, a number, an Array, `nil`) is sent as it is, as JSON. The
+proc gets a copy of the step. The status and the headers stay the same (JSON, `Cache-Control: no-store`,
+`Retry-After`, `X-Touchque-State`). One that raises, or a result that cannot be encoded, is logged
+(`[Touchque] errorBody failed: <message>`) and the default body is sent.
+
 ## Action types
 
 `"SEND_MONEY"` above is an action type: one kind of approval, with the title the phone shows and
@@ -89,6 +134,58 @@ The guard refuses what is not ready. A name that is not defined is a setup error
 turned off in the dashboard answers 403 with `reason: "action_disabled"`, which stops that kind of
 approval at once, without a deploy.
 
+## Guard inside your handler
+
+When your own checks come first (the balance, who owns the account), run the guard in your action,
+after them, with `Touchque::Guard.run`: the same two-phase contract as `require_touchque`, for Rails,
+Sinatra, Hanami or plain Rack.
+
+```ruby
+def create
+  # Your checks first, on every request (each poll comes back through them).
+  account = current_user.accounts.find(params.require(:from))
+  return render(json: { error: "insufficient_funds" }, status: 422) if account.balance < amount
+
+  input = Touchque::Guard.input_from_headers(->(name) { request.headers[name] })
+  result = Touchque::Guard.run(
+    Touchque.client, current_user.email, "SEND_MONEY",
+    details: { "Amount" => "#{amount} EUR", "To" => account.iban }, # shown on the phone, bound to the approval
+    ip: request.remote_ip, user_agent: request.user_agent, **input
+  )
+  if result[:approved]
+    Transfers.send!(account, amount) # approved: runs once
+    return render(json: { sent: true })
+  end
+
+  # Cache-Control: no-store, Retry-After on 423 / 429, X-Touchque-State (and -Reason) on 400 and above
+  Touchque::Guard.headers(result).each { |name, value| response.headers[name] = value }
+  render json: result[:body], status: result[:status]
+end
+```
+
+- **202** `{"touchque": step, "token": "..."}`: show the step and send the same request again with
+  `X-Touchque-Token: <token>` until it is approved (`@touchque/web` does this loop).
+- **200** with `result[:approved]`: run the action once. The approval is used up there: the same token
+  never approves twice.
+- **401, 403, 408, 423, 429, 500, 503**: send `status` and `body` as they are, with
+  `Touchque::Guard.headers(result)`: `Cache-Control: no-store`, `Retry-After` on 423 and 429,
+  `X-Touchque-State` and `X-Touchque-Reason`. For your own error shape,
+  `render json: Touchque::Guard.error_body(result, callable), status: result[:status]` sends what
+  `error_body:` would: it returns JSON text, and the default body (logged) when the callable raises.
+- **First-time QR**: a user with no phone linked gets the step `enroll` with
+  `enroll.qrCodeDataUrl`, the recovery codes and `enroll.expiresAt`. While the first-time QR is up,
+  polls answer `{state: "enroll", expiresAt}` without `enroll`: keep showing the QR you have. A new QR
+  comes with `enroll.qrCodeDataUrl` when the old one expired. Pages on `@touchque/web` need 2.1.0.
+- **Rate limits**: `Touchque::Guard.status_poll?` tells a poll from a new attempt (a poll only reads the
+  status). If you count attempts per user, pass `Touchque::Guard.run` `before_start:`, a callable it calls
+  when a first-time QR poll starts after all (the user linked, or the QR expired), to charge that start;
+  return a result to answer instead, or nil or false to go on (anything else answers 503). The relay does
+  this for `POST /login`.
+
+`Touchque.client` raises `Touchque::ConfigError` when a key is missing. `Touchque::Guard.default_client`
+returns `nil` instead (and logs it once), and `Touchque::Guard.misconfigured` is the 500 answer
+`require_touchque` sends then.
+
 ## The three primitives (any framework)
 
 ```ruby
@@ -100,7 +197,7 @@ approval = tq.complete(step["requestId"], "jane@acme.com", "SEND_MONEY", details
 ```
 
 `Touchque::Guard.run(tq, user, action, token:, offline:, code:, ...)` is the whole two-phase
-contract for Sinatra, Hanami or plain Rack.
+contract for Sinatra, Hanami or plain Rack: see "Guard inside your handler".
 
 ## Waiting in one call
 
@@ -132,8 +229,11 @@ Routes: `POST /login`, `/enroll/start`, `GET /enroll/status`, `/offline/challeng
 `/passkey/authenticate/options|verify`, `/passkey/login/options|verify`,
 `/passkey/register/options|verify`, `GET /passkey/credentials`, `DELETE /passkey/credentials/:id`.
 Pre-auth routes are rate limited (20 per IP, 5 per username a minute; pass `rate_limit: { store: }`
-for Redis across processes). The offline routes stay off until `get_login_user` is set. Adding a
-passkey for a user with a linked phone waits for the phone first.
+for Redis across processes). Polls of an approval on its way have their own per-IP budget; a
+first-time QR poll that starts after all (the user linked, or the QR expired) counts against the
+username's budget like a new attempt. Guard answers of 400 and above carry `X-Touchque-State` (and
+`X-Touchque-Reason`). The offline routes stay off until `get_login_user` is set. Adding a passkey for a
+user with a linked phone waits for the phone first.
 
 ## Webhooks
 

data/lib/touchque/client.rb

@@ -12,6 +12,9 @@ module Touchque
   #
   # Thread-safe: create one and reuse it (in Rails, Touchque.client).
   class Client
+    # @api private: the ConfigError message for a missing key or secret.
+    MISSING_KEYS = "Set TQ_API_KEY and TQ_API_SECRET (or pass api_key: and api_secret:)."
+
     attr_reader :auth, :login, :webauthn, :webhook, :offline, :action_types, :actions, :risk, :recovery,
                 :assist, :agents, :identity, :mobile, :qr_pairings, :device_risk, :safe_guard
 
@@ -21,9 +24,7 @@ module Touchque
       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, MISSING_KEYS if api_key.to_s.empty? || api_secret.to_s.empty?
       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")

data/lib/touchque/flow.rb

@@ -57,8 +57,7 @@ module Touchque
     # 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") }
+      enroll_qr(client.auth.generate_secret(user))
     rescue APIError => e
       raise unless e.status == 409
 
@@ -69,8 +68,38 @@ module Touchque
       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") }
+      enroll_qr(client.auth.reset_secret(user))
+    end
+
+    # The enroll step for a new linking QR. "expiresAt" is when the QR stops working: the
+    # API's expiresAt when it is an ISO 8601 date-time, else now + its ttlMs, else none.
+    def enroll_qr(res)
+      enroll = res.slice("qrCodeDataUrl", "recoveryCodes")
+      if iso_ms(res["expiresAt"])
+        enroll["expiresAt"] = res["expiresAt"]
+      elsif res["ttlMs"].is_a?(Numeric) && res["ttlMs"].positive?
+        enroll["expiresAt"] = iso_of(Util.now_ms + res["ttlMs"].to_i)
+      end
+      { "state" => "enroll", "enroll" => enroll }
+    end
+
+    ISO_8601 = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})\z/i
+
+    # @api private: milliseconds since the epoch of an ISO 8601 date-time with a zone
+    # ("2026-11-12T10:05:00.000Z"), or nil.
+    def iso_ms(value)
+      return nil unless value.is_a?(String) && value.match?(ISO_8601)
+
+      require "time"
+      time = Time.iso8601(value)
+      time.to_i * 1000 + time.usec / 1000
+    rescue ArgumentError
+      nil
+    end
+
+    # @api private: milliseconds since the epoch as ISO 8601 in UTC, like JavaScript's toISOString().
+    def iso_of(ms)
+      Time.at(ms / 1000, ms % 1000, :millisecond).utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
     end
 
     # "Why?": the case code and plain reasons of a login request's answer, for its step.
@@ -150,6 +179,9 @@ module Touchque
   #   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" => ...}}
+  #   first-time QR up        -> 202 {"touchque" => {"state" => "enroll", "expiresAt" => ...}} with no
+  #                              "enroll": keep showing the QR; a new one comes with
+  #                              "enroll" => {"qrCodeDataUrl"} once the old one expired
   # 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
@@ -164,6 +196,22 @@ module Touchque
     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
+    # A first-time QR this close to its expiry is replaced instead of kept on screen.
+    ENROLL_MARGIN_MS = 15_000
+    # The refusal message for a state when the guard set none (anything else: "The approval was refused.").
+    REFUSAL_MESSAGES = {
+      "rejected" => "The approval was rejected.",
+      "expired" => "The approval expired. Try again.",
+      "frozen" => "Too many rejected approvals. Try again later.",
+      "rate_limited" => "Too many attempts. Try again later."
+    }.freeze
+
+    @unconfigured_logged = false
+
+    class << self
+      # @api private: the adapters logged once that the client cannot be built.
+      attr_accessor :unconfigured_logged
+    end
 
     module_function
 
@@ -193,30 +241,132 @@ module Touchque
     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.
+    # bound to this user/action/details, still waiting, or showing the first-time QR while
+    # it is up (more than 15 s before it expires), and no offline switch or code. Relays do
+    # not count it against the per-user push limit. Such an enroll poll can still start
+    # (the user linked, or the QR is gone): relays charge that through run's before_start.
+    # Renewing an expiring QR counts.
     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"]
+      return false unless claims && bound?(claims, user, action, details, reference_id)
+      return claims["ee"].is_a?(Integer) && Util.now_ms < claims["ee"] - ENROLL_MARGIN_MS if claims["st"] == "enroll"
 
-      bound?(claims, user, action, details, reference_id) && WAITING.include?(claims["st"])
+      claims["rid"] ? WAITING.include?(claims["st"]) : false
+    end
+
+    # The headers for a result that is not an approval: Cache-Control: no-store,
+    # Retry-After when the step has one (423, 429) and, for status >= 400,
+    # X-Touchque-State plus X-Touchque-Reason when the step has a reason. @touchque/web
+    # rebuilds the step from them when a body has no "touchque" key; cross-origin pages
+    # need them in Access-Control-Expose-Headers.
+    def headers(result)
+      step = result[:body].is_a?(Hash) && result[:body]["touchque"].is_a?(Hash) ? result[:body]["touchque"] : {}
+      out = { "Cache-Control" => "no-store" }
+      out["Retry-After"] = step["retryAfter"].to_s if step["retryAfter"]
+      if result[:status] >= 400 && header_code?(step["state"])
+        out["X-Touchque-State"] = step["state"]
+        out["X-Touchque-Reason"] = step["reason"] if header_code?(step["reason"])
+      end
+      out
+    end
+
+    # A state or reason code that is safe as a header value.
+    def header_code?(value)
+      value.is_a?(String) && value.match?(/\A[A-Za-z0-9_.:-]{1,100}\z/)
     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
 
+    # Touchque.client for the per-route adapters: built on the request, kept once built.
+    # nil when it cannot be built (TQ_API_KEY / TQ_API_SECRET missing, a bad key or URL),
+    # logged once per process; the adapter then answers 500 misconfigured.
+    def default_client
+      Touchque.client
+    rescue ConfigError => e
+      unless Guard.unconfigured_logged
+        Guard.unconfigured_logged = true
+        line = if e.message.end_with?(Client::MISSING_KEYS)
+                 "[Touchque] TQ_API_KEY and TQ_API_SECRET are not set: routes guarded by Touchque answer 500 misconfigured."
+               else
+                 "[Touchque] #{e.message}"
+               end
+        Touchque.log :error, line
+      end
+      nil
+    end
+
+    # The 401 for a request without a signed-in user.
+    def unauthenticated
+      error(401, { "state" => "blocked", "reason" => "unauthenticated" }, "unauthenticated", "Sign in first.")
+    end
+
+    # The 500 for a setup error: missing keys, an undefined action type.
+    def misconfigured
+      error(500, { "state" => "blocked", "reason" => "misconfigured" }, "misconfigured", "Two-factor approval is not configured correctly.")
+    end
+
+    # What an error_body callable gets for a result with status >= 400:
+    # { status:, code:, message:, touchque: }. code: the error's code, else the step's
+    # reason, else its state; message: the error's message, else one for the state ("The
+    # approval was rejected." ...); touchque: a copy of the step as it would be sent.
+    def refusal(result)
+      body = Util.deep_copy(result[:body]) # the callable may change what it gets, never the answer
+      step = body["touchque"] || {}
+      error = body["error"] || {}
+      { status: result[:status], code: error["code"] || step["reason"] || step["state"],
+        message: error["message"] || REFUSAL_MESSAGES.fetch(step["state"], "The approval was refused."), touchque: step }
+    end
+
+    # Your own error shape for a result with status >= 400, as the JSON text to send: what
+    # +callable+ returns for refusal(result). What it encodes to decides (a Struct or Data as
+    # its Hash, to_hash, an as_json Hash, else to_json): a JSON object gets "touchque" set
+    # to the step, replacing yours, so @touchque/web still sees the state (no token is
+    # added); anything else is sent as it is. When the callable raises, or its result cannot
+    # be encoded, this logs "[Touchque] errorBody failed: ..." and returns the default body.
+    def error_body(result, callable)
+      json = jsonable(callable.call(refusal(result))).to_json
+      return json unless json.start_with?("{")
+
+      JSON.parse(json).merge("touchque" => result[:body]["touchque"]).to_json
+    rescue StandardError => e
+      Touchque.log :error, "[Touchque] errorBody failed: #{e.message}"
+      result[:body].to_json
+    end
+
+    # An error_body result in the form it is encoded in: a Struct or Data as its Hash, an
+    # object with to_hash as that, one whose as_json is a Hash as that; anything else as it is.
+    def jsonable(value)
+      case value
+      when Hash, Array, String, Numeric, Symbol, true, false, nil then value
+      when Struct then value.to_h
+      else
+        return value.to_h if defined?(::Data) && value.is_a?(::Data)
+        return value.to_hash if value.respond_to?(:to_hash)
+
+        json = value.respond_to?(:as_json) ? value.as_json : nil
+        json.is_a?(Hash) ? json : value
+      end
+    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.
+    # action once) or {status:, body: {"touchque" => step, "token" => ...}} to send back
+    # with headers(result).
     # 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.
+    # +before_start+ (for rate limiters): called at most once, only for a poll with a
+    # first-time QR token, right before it would start instead of keeping the QR (the user
+    # linked: the silent check or the push; the QR expired, is about to, or is gone: a new
+    # QR). Return nil or false to go on, or a result ({status:, body:}) to answer instead;
+    # anything else fails closed (503 unavailable), so nothing starts. A relay charges the
+    # user's budget there, since status_poll? exempted that poll.
     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
+            code: nil, code_type: nil, enroll: true, browser_proof: nil, silent_sign_in: false, context: nil, before_start: nil)
+      return unauthenticated if user.to_s.empty?
 
       norm = Details.normalize(details)
       norm = nil if norm.empty?
@@ -227,6 +377,11 @@ module Touchque
         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"]
+        # A first-time QR: its token carries when the QR expires (ee), so polls keep it on screen.
+        if step["state"] == "enroll" && step["enroll"].is_a?(Hash) && !step["enroll"]["qrCodeDataUrl"].to_s.empty?
+          ee = Steps.iso_ms(step["enroll"]["expiresAt"])
+          claims["ee"] = ee if ee
+        end
         claims.merge!(extra)
         { status: STATUS.fetch(step["state"]), body: { "touchque" => step.compact, "token" => Steps.sign_guard_token(secret, claims) } }
       end
@@ -313,6 +468,26 @@ module Touchque
           return issue.call({ "state" => now["state"], "requestId" => rid })
         end
 
+        # The first-time QR is up: while the phone is not linked and the QR lives, keep it on screen
+        # (no new secret, no push); the page keeps the QR and recovery codes it shows. Linked,
+        # expiring or gone: start.
+        if bound && st == "enroll" && (ee = bound["ee"]).is_a?(Integer)
+          if link_state(client, user) == false && Util.now_ms < ee - ENROLL_MARGIN_MS
+            return issue.call({ "state" => "enroll", "expiresAt" => Steps.iso_of(ee) }, { "ee" => ee })
+          end
+
+          # This poll starts after all (a push, or a new QR): the caller may charge or refuse it first.
+          # Anything truthy it returns is the answer; what is not a result fails closed (503).
+          instead = before_start&.call
+          if instead
+            unless instead.is_a?(Hash) && instead[:status].is_a?(Integer) && instead[:body].is_a?(Hash)
+              raise ArgumentError, "before_start must return nil or false to go on, or a result { status:, body: } to answer"
+            end
+
+            return instead
+          end
+        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)
@@ -323,7 +498,7 @@ module Touchque
                                                      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.")
+        misconfigured
       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.
@@ -336,6 +511,17 @@ module Touchque
       { status: status, body: { "touchque" => step, "error" => { "code" => code, "message" => message } } }
     end
 
+    # Whether a phone is linked to the user (used, or a deviceId); nil when Touchque does
+    # not know the user (404: the QR is gone). Other errors raise.
+    def link_state(client, user)
+      current = client.auth.get_user(user)
+      current["used"] || current["deviceId"] ? true : false
+    rescue APIError => e
+      raise unless e.status == 404
+
+      nil
+    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

data/lib/touchque/rails/guard.rb

@@ -20,17 +20,38 @@ module Touchque
     # 423 / 429 with Retry-After. Options: user: (default: current_user's email, id or
     # username; for your login action, whoever just passed your password check), details:,
     # reference_id:, context: (procs run in the controller, or method names),
-    # silent_sign_in: (true or { max_age_seconds: }), enroll:, and before_action's
-    # only: / except: / if: / unless:.
+    # silent_sign_in: (true or { max_age_seconds: }), enroll:, error_body:, and
+    # before_action's only: / except: / if: / unless:.
+    #
+    # Every answer of 400 and above carries X-Touchque-State (and X-Touchque-Reason when the
+    # step has a reason).
+    #
+    # error_body: your own error shape for every answer of 400 and above (never a 202 step,
+    # never an approval): a proc run in the controller, or a method name, given the refusal
+    # ({ status:, code:, message:, touchque: }, with a copy of the step). What it encodes to
+    # decides: a JSON object (a Hash, Struct, Data...) is sent with "touchque" set to the
+    # step; anything else as it is. Status and headers stay; one that raises, or a result
+    # that cannot be encoded, is logged and the default body sent.
+    #
+    #   require_touchque "SEND_MONEY", error_body: ->(r) { { message: r[:message], code: r[:code] } }
+    #
+    # Touchque.client is built on the first request: without TQ_API_KEY / TQ_API_SECRET the
+    # action answers 500 misconfigured (401 without a signed-in user) and never runs.
     module Guard
       def self.included(base)
         base.extend(ClassMethods)
       end
 
       module ClassMethods
-        def require_touchque(action, user: nil, details: nil, reference_id: nil, context: nil, silent_sign_in: false, enroll: true, **filter_options)
+        def require_touchque(action, user: nil, details: nil, reference_id: nil, context: nil, silent_sign_in: false, enroll: true,
+                             error_body: nil, **filter_options)
           Touchque::Guard.assert_silent_sign_in!(silent_sign_in, "require_touchque")
-          options = { user: user, details: details, reference_id: reference_id, context: context, silent_sign_in: silent_sign_in, enroll: enroll }
+          unless error_body.nil? || error_body.is_a?(Symbol) || error_body.respond_to?(:call)
+            raise ArgumentError, "require_touchque: error_body must be a proc, a method name or respond to call."
+          end
+
+          options = { user: user, details: details, reference_id: reference_id, context: context, silent_sign_in: silent_sign_in,
+                      enroll: enroll, error_body: error_body }
           before_action(**filter_options) { touchque_guard!(action, options) }
         end
       end
@@ -43,25 +64,44 @@ module Touchque
       private
 
       def touchque_guard!(action, options)
-        header = ->(name) { request.headers[name] }
-        input = Touchque::Guard.input_from_headers(header)
-        silent = options[:silent_sign_in]
-        result = Touchque::Guard.run(
-          Touchque.client, touchque_value(options[:user]) || touchque_default_user, action,
-          details: touchque_value(options[:details]), reference_id: touchque_value(options[:reference_id]),
-          ip: request.remote_ip, user_agent: request.user_agent, token: input[:token], offline: input[:offline],
-          code: input[:code], code_type: input[:code_type], enroll: options[:enroll],
-          browser_proof: Touchque::Guard.silent_on?(silent) ? header.call(Touchque::Guard::BROWSER_HEADER) : nil,
-          silent_sign_in: silent, context: touchque_value(options[:context])
-        )
+        user = touchque_value(options[:user]) || touchque_default_user
+        client = Touchque::Guard.default_client
+        result = if client.nil?
+                   # No client (TQ_API_KEY / TQ_API_SECRET missing): an answer, never an exception.
+                   user.to_s.empty? ? Touchque::Guard.unauthenticated : Touchque::Guard.misconfigured
+                 else
+                   header = ->(name) { request.headers[name] }
+                   input = Touchque::Guard.input_from_headers(header)
+                   silent = options[:silent_sign_in]
+                   Touchque::Guard.run(
+                     client, user, action,
+                     details: touchque_value(options[:details]), reference_id: touchque_value(options[:reference_id]),
+                     ip: request.remote_ip, user_agent: request.user_agent, token: input[:token], offline: input[:offline],
+                     code: input[:code], code_type: input[:code_type], enroll: options[:enroll],
+                     browser_proof: Touchque::Guard.silent_on?(silent) ? header.call(Touchque::Guard::BROWSER_HEADER) : nil,
+                     silent_sign_in: silent, context: touchque_value(options[:context])
+                   )
+                 end
         if result[:approved]
           request.env["touchque.approval"] = result[:approved]
           return
         end
-        response.headers["Cache-Control"] = "no-store"
-        retry_after = result[:body].dig("touchque", "retryAfter")
-        response.headers["Retry-After"] = retry_after.to_s if retry_after
-        render json: result[:body], status: result[:status]
+        Touchque::Guard.headers(result).each { |name, value| response.headers[name] = value }
+        render json: touchque_body(result, options[:error_body]), status: result[:status]
+      end
+
+      # The guard's body, or error_body's (JSON text; the default body when it fails) for an
+      # answer of 400 and above.
+      def touchque_body(result, error_body)
+        return result[:body] if error_body.nil? || result[:status] < 400
+
+        Touchque::Guard.error_body(result, lambda { |refusal|
+          case error_body
+          when Proc then instance_exec(refusal, &error_body)
+          when Symbol then send(error_body, refusal)
+          else error_body.call(refusal)
+          end
+        })
       end
 
       def touchque_value(option)

data/lib/touchque/relay.rb

@@ -221,17 +221,25 @@ module Touchque
       details = @get_details&.call(ctx[:req])
       proof = Guard.silent_on?(@silent_sign_in) ? Guard.presence(ctx[:header].call(Guard::BROWSER_HEADER)) : nil
       # Polling an approval already sent is not a new attempt: its own, larger per-IP budget.
-      limited = if Guard.status_poll?(@tq, user, @action_type, details: details, token: input[:token], offline: input[:offline], code: input[:code])
-                  allow(ctx, "login-poll", nil, POLLS_PER_ATTEMPT)
-                else
-                  allow(ctx, "login", user)
-                end
+      poll = Guard.status_poll?(@tq, user, @action_type, details: details, token: input[:token], offline: input[:offline], code: input[:code])
+      limited = poll ? allow(ctx, "login-poll", nil, POLLS_PER_ATTEMPT) : allow(ctx, "login", user)
       return limited if limited
 
+      # A first-time QR poll that starts after all (the user linked, or the QR is gone) is
+      # charged like a new attempt: a replayed token must not push on the poll budget.
+      refused = nil
+      before_start = if poll
+                       lambda do
+                         refused = allow(ctx, "login", user)
+                         refused && { status: refused.status, body: refused.body }
+                       end
+                     end
       result = Guard.run(@tq, user, @action_type, details: details, ip: ctx[:ip].empty? ? nil : ctx[:ip], user_agent: ctx[:user_agent],
                                                   token: input[:token], offline: input[:offline], code: input[:code], code_type: input[:code_type],
                                                   # Pre-auth: a typed username proves nothing, so no linking QR unless get_login_user ties this route to the password step.
-                                                  enroll: !@get_login_user.nil?, browser_proof: proof, silent_sign_in: @silent_sign_in)
+                                                  enroll: !@get_login_user.nil?, browser_proof: proof, silent_sign_in: @silent_sign_in,
+                                                  before_start: before_start)
+      return refused if refused
       return guard_response(result) unless result[:approved]
 
       approved = result[:approved]
@@ -248,11 +256,11 @@ module Touchque
       end
     end
 
+    # A guard answer that is not an approval, with Guard.headers (no-store, Retry-After, X-Touchque-State / -Reason).
     def guard_response(result)
       res = RelayResponse.new(result[:status], result[:body])
-      retry_after = result[:body].dig("touchque", "retryAfter")
-      res.set_header("Retry-After", retry_after) if retry_after
-      res.set_header("Cache-Control", "no-store")
+      Guard.headers(result).each { |name, value| res.set_header(name, value) }
+      res
     end
 
     # The username used for on_authenticated is the one Touchque returns for the code, never the body's.

data/lib/touchque/util.rb

@@ -83,6 +83,16 @@ module Touchque
       end
     end
 
+    # A deep copy of JSON-like data: Hashes, Arrays and Strings copied, anything else as it is.
+    def deep_copy(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, deep_copy(v)] }
+      when Array then value.map { |v| deep_copy(v) }
+      when String then value.dup
+      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?) }

data/lib/touchque/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: touchque
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Touchque