touchque 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd0417df799898bf80db545d3ce9d62bc81ea1fb537631ed1e2d869c389e8e6
-  data.tar.gz: ff2565d595c4b7e93c117bf6e414cadb9278d2f739b52a80eec00b0995424bed
+  metadata.gz: 2762f3481ee0053340ce39c7c40d37dbc67d0394ea86859b6d1c7ab55b9ec015
+  data.tar.gz: 4706b4df98f10c0b2f6ade9bb4fe6fad7de8a725719f52bb439a80dc63059cad
 SHA512:
-  metadata.gz: 4bb3567bcc20f35485e45312095b1285c9877e85058bd716ca4409af75e050783177491200fde593d4c06de0e35a7e260072c3bf10afc0a67d6d522392074e76
-  data.tar.gz: 5c38f7c2d6af269aeb6afff09aafd4214d43dd8c001496d9ad541e6f9b734738198e2784285a77fc7644d4520f4e920e5987f2edbb92f154bdc6067f92eb5bd5
+  metadata.gz: e3942fa2fc614a43b07f8d990948ce2dd49bf783f5562f1d72c8ff6a8ecc3863f68a3207abd6cb31e63edece987bc45b35774f7792c6b8ccf0d8724c8a0d0361
+  data.tar.gz: a97d8111e607aaac9b4e8cd6664dfce13dbd04dff70e39a12f8d0928e761ac408fdc44741fc1a2fe92b369c90167d8c531da9d09c34f7a966f7bc068f012997c

data/CHANGELOG.md

@@ -3,6 +3,23 @@
 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/).
 
+## [5.2.0] — 2026-11-13
+
+### Fixed
+- **`Touchque::Guard.run(nil, ...)` no longer raises `NoMethodError`.** `nil` is `Touchque::Guard.default_client` (`Touchque.client`, built on the first request that needs it and kept once built; a failed build is tried again on the next request). While it cannot be built the guard answers 500 `misconfigured` (401 `unauthenticated` without a user), logged once through `Touchque.logger`. `Touchque::Guard.status_poll?(nil, ...)` takes it too and is false while it cannot be built.
+
+### Added
+- **`Touchque::Guard.default_client = client`** makes `client` the default client (`Touchque.client`) of `Touchque::Guard.run(nil, ...)`, `status_poll?(nil, ...)` and `require_touchque`: the way to give them your own client. `nil` forgets it, so the next call builds from `config.touchque` / the environment again. `FakeTouchque#install` sets it. At boot, `Touchque.client` is the fail-fast check: it raises `Touchque::ConfigError`, naming what is missing.
+- **`Touchque::Guard.response(result, error_body: nil)`** gives `[status, headers, body]` for a result that is not an approval, Rack style, exactly as `require_touchque` and the relay send it (both use it now): the body as JSON text; `content-type`, `cache-control: no-store`, `retry-after` on 423 / 429 and `x-touchque-state` / `x-touchque-reason` on 400 and above, with lower-case names (Rack 3); `error_body:` with the 5.1 rules (a callable that raises, or a result that cannot be encoded, is logged and the default body sent). It raises `ArgumentError` for an approval.
+- **`Touchque::Testing::FakeTouchque`** (`require "touchque/testing"`): a `Touchque::Client` that answers in memory, for your app's tests, with no network, no API keys and no Node.js. The real guard runs. `link` / `unlink`, `approve` / `reject` / `expire` (the latest request or one by id; `via: "WEBAUTHN"`), `auto_approve`, `number_match`, `secret_ttl_ms`, the offline code `ABCD123` and the time-based code `123456`, `requests` and `calls`, and `install` / `uninstall` (or `install { ... }`) as `Touchque.client`. Each request keeps its expiry and answers it on its status check, like the API. `Touchque::Testing::FakeClient` is another name for it.
+- In Rails the Railtie sets `Touchque.logger` to `Rails.logger` when the app set none, so the SDK's "logged once" lines reach your log. Your own (or `nil`) in an initializer wins.
+
+### Changed
+- **Waiting polls carry `expiresAt`.** A `waiting` or `passkey_required` step with `expiresAt` puts it in its token (claim `rx`, ms since the epoch), and every later answer for that request in those two states carries `expiresAt`: the live one from Touchque's status answer when it has one (a push moved to a passkey during a call gets 180 s more), else the token's. The new token keeps the value used, and the offline QR next to the push carries it on. Only the first answer had it, so a page reading it from the latest answer never stopped by time. `Touchque::Steps.check` gives the live `expiresAt` while a request waits. With neither, polls answer as before.
+- **`enroll: false` says why.** A user with no phone on a guard that may not show the linking QR gets 202 `{"touchque":{"state":"enroll","reason":"enrollment_off"}}` instead of a bare `enroll` step: `require_touchque` and `Touchque::Guard.run` with `enroll: false`, the relay's `POST /login` without `get_login_user` and its passkey registration. `@touchque/web` 2.2.0 stops polling on it.
+- The relay's guard answers name their headers in lower case (`cache-control`, `x-touchque-state` ...), as `Touchque::Guard.response` gives them; `RelayResponse#header` reads names case-insensitively as before.
+- README: "Guard inside your handler" passes `nil` (not `Touchque.client`, which raises without keys) and answers with `Touchque::Guard.response`; it shows `Touchque::Guard.default_client =` and the fail-fast `Touchque.client` at boot, says that a new first-time QR comes about 15 s before the old one expires with new recovery codes (the old QR and codes stop working) and that a first-time QR poll is charged once the QR is gone or within about 15 s of expiring, that waiting polls carry `expiresAt`, what `enrollment_off` means, and that `passkey_required`, `offline` and an `enroll` step with a reason need `@touchque/web` or your own UI following the contract. New section "Testing your routes" with Rails and Rack request tests on `FakeTouchque`.
+
 ## [5.1.0] — 2026-11-12
 
 ### Fixed

data/README.md

@@ -65,7 +65,9 @@ does this loop for you. Once approved the action runs **once**. Refusals answer
 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`.
+without `enroll`, so keep showing the QR you have. About 15 s before it expires a new QR comes with
+`enroll.qrCodeDataUrl` and new recovery codes: the old QR and the old codes stop working. The other states
+are listed under [Guard inside your handler](#guard-inside-your-handler).
 
 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] }`.
@@ -79,9 +81,10 @@ Without `TQ_API_KEY` / `TQ_API_SECRET` (or `config.touchque`) nothing raises: th
 **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."
+`Touchque.logger` (in Rails, `Rails.logger` unless you set one): `[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
@@ -148,7 +151,8 @@ def create
 
   input = Touchque::Guard.input_from_headers(->(name) { request.headers[name] })
   result = Touchque::Guard.run(
-    Touchque.client, current_user.email, "SEND_MONEY",
+    nil, # the client: Touchque.client, built on this request, then kept
+    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
   )
@@ -157,35 +161,59 @@ def create
     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]
+  # Not approved (yet): what require_touchque sends for the same result.
+  status, headers, body = Touchque::Guard.response(result)
+  response.headers.merge!(headers)
+  render json: body, status: status
 end
 ```
 
+In Sinatra or plain Rack, `status, headers, body = Touchque::Guard.response(result)` and answer
+`[status, headers, [body]]`.
+
+- **The client.** `nil` is `Touchque::Guard.default_client`: `Touchque.client`, built from
+  `config.touchque` or `TQ_API_KEY` / `TQ_API_SECRET` on the first request that needs it and kept once
+  built, so nothing raises at boot or in a request. While a key is missing the answer is 500
+  `misconfigured` (401 `unauthenticated` without a user), logged once through `Touchque.logger`, and a
+  later request tries again. Do not pass `Touchque.client` itself: it raises `Touchque::ConfigError`
+  without keys. `Touchque::Guard.status_poll?` takes `nil` the same way.
+- **Your own client for `nil`** (your `base_url:`, say): `Touchque::Guard.default_client =
+  Touchque::Client.new(...)` once at boot; `Touchque::Guard.default_client = nil` forgets it, and the
+  next call builds from `config.touchque` / the environment again. The SDK logs through `Touchque.logger`
+  (in Rails, `Rails.logger` unless you set one). To fail fast at boot instead of answering 500, call
+  `Touchque.client` there: it raises `Touchque::ConfigError`, naming what is missing
+  (`Touchque::Guard.default_client` answers `nil` instead, and logs it once).
 - **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).
+  `X-Touchque-Token: <token>` until it is approved (`@touchque/web` does this loop). While it waits
+  (`waiting`, `passkey_required`), every answer carries the request's `expiresAt`, as Touchque has it now
+  (a push moved to a passkey during a call gets more time): stop polling once it is past.
 - **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.
+  never approves twice. `Touchque::Guard.response` raises `ArgumentError` for it.
+- **401, 403, 408, 423, 429, 500, 503**: `Touchque::Guard.response(result)` gives `[status, headers,
+  body]`, Rack style: the body as JSON text, the headers with lower-case names (`content-type`,
+  `cache-control: no-store`, `retry-after` on 423 and 429, `x-touchque-state` and `x-touchque-reason`).
+  For your own error shape pass a callable,
+  `Touchque::Guard.response(result, error_body: ->(r) { { message: r[:message], code: r[:code] } })`:
+  the rules of `require_touchque`'s `error_body:`; one that raises, or a result that cannot be encoded,
+  is logged and the default body sent.
 - **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.
+  polls answer `{state: "enroll", expiresAt}` without `enroll`: keep showing the QR you have. About 15 s
+  before it expires a poll brings a new QR with `enroll.qrCodeDataUrl` and new recovery codes: the old
+  QR and the old codes stop working. Pages on `@touchque/web` need 2.1.0.
+- **No linking QR** (`enroll: false`, on `Touchque::Guard.run` or `require_touchque`; the relay's
+  pre-auth `POST /login` and its passkey registration do the same): a user with no phone gets 202
+  `{"touchque": {"state": "enroll", "reason": "enrollment_off"}}`. It is final: stop polling and tell
+  them to link the Touchque app first.
+- **Other 202 states** (`passkey_required`, `offline`, an `enroll` with a `reason`) need
+  `@touchque/web`, or your own UI following the contract.
 - **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;
+  when a first-time QR poll starts after all (the user linked, or the QR is gone or within about 15 s of
+  expiring), 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
@@ -196,7 +224,7 @@ approval = tq.complete(step["requestId"], "jane@acme.com", "SEND_MONEY", details
 # uses the approval once, and only for this user, action and amount
 ```
 
-`Touchque::Guard.run(tq, user, action, token:, offline:, code:, ...)` is the whole two-phase
+`Touchque::Guard.run(nil, user, action, token:, offline:, code:, ...)` is the whole two-phase
 contract for Sinatra, Hanami or plain Rack: see "Guard inside your handler".
 
 ## Waiting in one call
@@ -230,10 +258,12 @@ Routes: `POST /login`, `/enroll/start`, `GET /enroll/status`, `/offline/challeng
 `/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). 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.
+first-time QR poll that starts after all (the user linked, or the QR is gone or within about 15 s of
+expiring) 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, and without it
+`POST /login` never shows the linking QR: a user with no phone gets 202
+`{"touchque": {"state": "enroll", "reason": "enrollment_off"}}`. Adding a passkey for a user with a
+linked phone waits for the phone first.
 
 ## Webhooks
 
@@ -446,6 +476,79 @@ end
 
 `Touchque::SafeApproval.verify` makes the guard's check off chain, so a co-signer or your own server never has to trust Touchque: it computes the Safe transaction hash (EIP-712) and the governance hash from the raw fields, rebuilds the 149-byte message the phone signed and checks the P-256 signature. `purpose:` defaults to `"approve"`: a schedule approval covers no Safe nonce or gas fields, so it is accepted only when you pass `purpose: "schedule"`, never as permission to execute. It refuses a high `s`, an approval that expired or is valid for more than a day, another approver index, and, when you pass `rows:` or `display_digest:` from your own decoding, rows the phone did not show. `"reason"` is `approval_malformed`, `public_key_invalid`, `approver_index_mismatch`, `approval_expired`, `rows_differ`, `high_s` or `signature_invalid`. `safe_tx_hash`, `governance_hash`, `message` and `display_digest` are public too.
 
+## Testing your routes
+
+`Touchque::Testing::FakeTouchque` (`require "touchque/testing"`) is a `Touchque::Client` that answers in
+memory: no network, no API keys, no Node.js. The real guard runs, so your routes answer what they answer
+in production, and your test plays the phone. A Rails request test:
+
+```ruby
+# test/integration/transfers_test.rb
+require "test_helper"
+require "touchque/testing"
+
+class TransfersTest < ActionDispatch::IntegrationTest
+  setup { @tq = Touchque::Testing::FakeTouchque.new.install } # now Touchque.client
+  teardown { @tq.uninstall }
+
+  test "a transfer needs an approval on the phone" do
+    sign_in_as users(:jane) # your own sign-in helper
+    post transfers_path, params: { amount: 5 }, as: :json
+    assert_response :accepted # 202: the step and a token
+    token = response.parsed_body["token"]
+
+    @tq.approve # the person approves on the phone
+    post transfers_path, params: { amount: 5 }, as: :json, headers: { "X-Touchque-Token" => token }
+    assert_response :success
+    assert_equal [{ "label" => "Amount", "value" => "5 EUR" }], @tq.requests.last["details"]
+  end
+end
+```
+
+Sinatra or plain Rack, with `rack-test`:
+
+```ruby
+require "rack/test"
+require "touchque/testing"
+
+class TransferTest < Minitest::Test
+  include Rack::Test::Methods
+
+  def app = MyApp # Touchque::Guard.run(nil, ...) in its route
+
+  def test_a_transfer_needs_an_approval
+    Touchque::Testing::FakeTouchque.new.install do |tq| # the default client inside the block
+      post "/transfer", JSON.generate(amount: 5), "CONTENT_TYPE" => "application/json"
+      assert_equal 202, last_response.status
+      tq.approve
+      header "X-Touchque-Token", JSON.parse(last_response.body)["token"]
+      post "/transfer", JSON.generate(amount: 5), "CONTENT_TYPE" => "application/json"
+      assert_equal 200, last_response.status
+    end
+  end
+end
+```
+
+- `install` makes the fake the default client (`Touchque::Guard.default_client = tq`, so
+  `Touchque.client`), which `require_touchque`, `Touchque::Guard.run(nil, ...)` and a relay given no
+  `client:` use, until `uninstall`; with a block, for the block only. Install it
+  after your app configured Touchque (`Touchque.configure` drops it). A `Touchque::Rack::Relay` keeps the
+  client of its first request: give it `client: tq` in a test that builds it.
+- `tq.approve`, `tq.reject`, `tq.expire`: the latest request, or one by its id
+  (`tq.approve(request_id)`; `via: "WEBAUTHN"` approves with a passkey).
+- `FakeTouchque.new(auto_approve: true)` (or `tq.auto_approve = true`): every request is approved as it
+  is made. The first request still answers 202; the next one runs the action.
+- Every user has a phone linked. `tq.unlink(user)` shows them the first-time QR instead
+  (`FakeTouchque.new(linked: false)`: nobody has one); `tq.link(user)` is the phone scanning it.
+  `tq.secret_ttl_ms` is how long a QR works (5 minutes).
+- `FakeTouchque.new(number_match: true)`: pushes ask for the number `47`.
+- `tq.requests` (`"id"`, `"user"`, `"type"`, `"details"`, `"referenceId"`, `"status"`, `"expiresAt"`,
+  answered on each status check) and `tq.calls` (`"method"`, `"path"`, `"body"`): what your app asked
+  Touchque, in order.
+- Offline approval: the code is `ABCD123` (`FakeTouchque::OFFLINE_CODE`), the time-based code `123456`
+  (`FakeTouchque::TOTP_CODE`). Calls outside the step-up (recovery, agents …) raise
+  `Touchque::APIError` 404. `Touchque::Testing::FakeClient` is another name for it.
+
 ## Errors, case codes and retries
 
 | Error | When |
@@ -468,7 +571,7 @@ never follows redirects and refuses plain `http://` except for localhost.
 
 ## Logging
 
-The SDK writes nothing to `$stderr` on its own. To see its own problems (a misconfigured guard, a failed `on_challenge`, a relay without `get_login_user`), set a logger: `Touchque.logger = Rails.logger` (or any `Logger`). Lines carry an error's class and message, never the request.
+The SDK writes nothing to `$stderr` on its own. To see its own problems (a misconfigured guard, a failed `on_challenge`, a relay without `get_login_user`), set a logger: `Touchque.logger = Logger.new($stdout)` (or any `Logger`). In Rails the Railtie sets it to `Rails.logger` when your app set none; set your own in an initializer (`nil` for none). Lines carry an error's class and message, never the request.
 
 ## Development
 

data/lib/touchque/client.rb

@@ -28,7 +28,7 @@ module Touchque
       raise ConfigError, "api_key must start with \"tq_\". Did you accidentally swap api_key and api_secret?" unless api_key.start_with?("tq_")
 
       Util.assert_safe_url!(base_url, "base_url")
-      @http = HTTP.new(api_key: api_key, api_secret: api_secret, base_url: base_url.chomp("/"), timeout: timeout)
+      @http = transport(api_key: api_key, api_secret: api_secret, base_url: base_url.chomp("/"), timeout: timeout)
       @auth = Resources::Auth.new(@http)
       @login = Resources::Login.new(@http)
       @webauthn = Resources::WebAuthn.new(@http)
@@ -78,5 +78,12 @@ module Touchque
       login.verify(user, type: type, **options)
       yield
     end
+
+    private
+
+    # What every resource calls the API through (Touchque::Testing::FakeTouchque answers in memory).
+    def transport(**options)
+      HTTP.new(**options)
+    end
   end
 end

data/lib/touchque/flow.rb

@@ -11,7 +11,8 @@ module Touchque
 
     module_function
 
-    # Starts an approval for +action+; never waits.
+    # Starts an approval for +action+; never waits. A user with no phone linked gets the
+    # linking QR ("enroll"); with enroll: false, {"state" => "enroll", "reason" => "enrollment_off"}.
     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?
 
@@ -37,7 +38,8 @@ module Touchque
         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" }
+          # No phone, and this guard may not show the linking QR: final, a page stops polling.
+          return enroll ? enroll_step(client, user) : { "state" => "enroll", "reason" => "enrollment_off" }
         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
@@ -113,12 +115,15 @@ module Touchque
       out
     end
 
-    # Where a started approval is now.
+    # Where a started approval is now. While it waits (waiting, passkey_required) the step has
+    # the request's live "expiresAt" when Touchque sends it: a switch to a passkey during a call
+    # extends it.
     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["expiresAt"] = s["expiresAt"] if %w[waiting passkey_required].include?(state) && iso_ms(s["expiresAt"])
       step
     end
 
@@ -177,11 +182,15 @@ module Touchque
   # 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
+  #   repeat with the token   -> 202 while waiting (each answer carries the request's live "expiresAt"),
+  #                              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
+  #                              "enroll": keep showing the QR; about 15 s before it expires a new one
+  #                              comes with "enroll" => {"qrCodeDataUrl"} and new recovery codes
+  #   no phone, enroll: false -> 202 {"touchque" => {"state" => "enroll", "reason" => "enrollment_off"}}: final
+  # run(nil, ...) uses default_client (Touchque.client; set with default_client=); response(result)
+  # gives the Rack-style answer to send.
   # 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
@@ -196,6 +205,8 @@ 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
+    # Steps whose token carries the request's expiry (claim "rx"): every poll answers an expiresAt.
+    EXPIRING = %w[waiting passkey_required].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.").
@@ -245,10 +256,14 @@ module Touchque
     # 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.
+    # Renewing an expiring QR counts. +client+: as run's; nil is default_client, and false
+    # while it cannot be built.
     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?
 
+      client ||= default_client
+      return false unless client
+
       claims = Steps.verify_guard_token(client.api_secret, token)
       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"
@@ -281,9 +296,11 @@ module Touchque
       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.
+    # Touchque.client for run(nil, ...) and 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 through Touchque.logger; the guard then answers
+    # 500 misconfigured, and a later request tries again. To fail fast at boot instead, call
+    # Touchque.client there: it raises Touchque::ConfigError, naming what is missing.
     def default_client
       Touchque.client
     rescue ConfigError => e
@@ -299,6 +316,14 @@ module Touchque
       nil
     end
 
+    # Makes +client+ the default client (Touchque.client) of run(nil, ...), status_poll?(nil,
+    # ...) and require_touchque: the way to give them your own client (built with your
+    # base_url, say; Touchque.logger is the SDK's logger). nil forgets it, so the next call
+    # builds from Touchque.configure / the environment again.
+    def default_client=(client)
+      Touchque.client = client
+    end
+
     # The 401 for a request without a signed-in user.
     def unauthenticated
       error(401, { "state" => "blocked", "reason" => "unauthenticated" }, "unauthenticated", "Sign in first.")
@@ -337,6 +362,30 @@ module Touchque
       result[:body].to_json
     end
 
+    JSON_TYPE = "application/json; charset=utf-8"
+
+    # The HTTP answer for a result of run that is not an approval, Rack style:
+    # [status, headers, body], the body as JSON text: what require_touchque and the relay
+    # send for it. headers: content-type, cache-control: no-store, retry-after on 423 / 429
+    # and, on 400 and above, x-touchque-state / x-touchque-reason (lower-case names, as Rack 3
+    # wants). +error_body+: a callable for your own error shape on 400 and above, as
+    # error_body(result, callable): one that raises, or a result that cannot be encoded, is
+    # logged and the default body sent. An approval raises ArgumentError: run your action.
+    #
+    #   status, headers, body = Touchque::Guard.response(result)
+    #   [status, headers, [body]] # a Rack response
+    def response(result, error_body: nil)
+      raise ArgumentError, "Guard.response: the result is an approval: run your action instead" if result[:approved]
+      unless error_body.nil? || error_body.respond_to?(:call)
+        raise ArgumentError, "Guard.response: error_body must respond to call"
+      end
+
+      body = error_body && result[:status] >= 400 ? Guard.error_body(result, error_body) : result[:body].to_json
+      out = { "content-type" => JSON_TYPE }
+      Guard.headers(result).each { |name, value| out[name.downcase] = value }
+      [result[:status], out, body]
+    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)
@@ -353,8 +402,13 @@ module Touchque
     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
-    # with headers(result).
+    # action once) or {status:, body: {"touchque" => step, "token" => ...}} to send back as
+    # response(result) gives it.
+    # +client+: your Touchque::Client, or nil for default_client (Touchque.client, built on
+    # the first request that needs it; while it cannot be built the answer is 500
+    # misconfigured, 401 unauthenticated without a user, logged once).
+    # +enroll+: false for a guard that may not show the linking QR: a user with no phone gets
+    # 202 {"state" => "enroll", "reason" => "enrollment_off"}.
     # 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.
@@ -368,6 +422,9 @@ module Touchque
             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?
 
+      client ||= default_client
+      return misconfigured unless client
+
       norm = Details.normalize(details)
       norm = nil if norm.empty?
       base = { "u" => user, "a" => action, "d" => Details.digest(details), "r" => reference_id }
@@ -377,6 +434,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 push or passkey: its token carries when the request expires (rx), for polls without a live expiry.
+        if EXPIRING.include?(step["state"])
+          expiry = Steps.iso_ms(step["expiresAt"])
+          claims["rx"] = expiry if expiry
+        end
         # 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"])
@@ -393,7 +455,15 @@ module Touchque
         n = bound && bound["n"]
         oc = bound && bound["oc"]
         st = bound && bound["st"]
-        keep = { "oc" => oc, "rid" => rid, "n" => n }
+        # The request's expiry (rx) stays with it: waiting / passkey answers carry it as expiresAt (the
+        # live one from Touchque's status answer when there is one), and the offline steps carry it on.
+        rx = bound && bound["rx"].is_a?(Integer) ? bound["rx"] : nil
+        keep_rx = rx ? { "rx" => rx } : {}
+        expiring = lambda do |step, live = nil|
+          at = live || rx
+          at ? step.merge("expiresAt" => Steps.iso_of(at)) : step
+        end
+        keep = { "oc" => oc, "rid" => rid, "n" => n }.merge(keep_rx)
 
         # Offline: the user typed the code from the phone.
         if bound && !code.to_s.empty? && (st == "offline" || code_type == "totp")
@@ -416,7 +486,7 @@ module Touchque
           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 })
+            return issue.call(expiring.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" })
@@ -428,12 +498,12 @@ module Touchque
             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 })
+            return issue.call({ "state" => "offline", "offline" => offline_step }, { "rid" => rid, "n" => ch["challengeCode"] || n }.merge(keep_rx))
           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 })
+              return issue.call(expiring.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
 
@@ -444,6 +514,8 @@ module Touchque
         # 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)
+          # The live expiry: a switch to a passkey during a call extends it. The new token keeps it (rx).
+          live = Steps.iso_ms(now["expiresAt"])
           if now["state"] == "approved"
             begin
               return { status: 200, approved: Steps.complete(client, rid, user, action, details: details, reference_id: reference_id) }
@@ -455,13 +527,15 @@ module Touchque
           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 })
+            return issue.call(expiring.call({ "state" => "passkey_required", "requestId" => rid, "number" => n }, live), { "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 st == "offline" && %w[waiting expired].include?(now["state"])
+            return issue.call({ "state" => "offline", "offline" => { "challengeId" => oc.to_s } }, live ? keep.merge("rx" => live) : keep)
+          end
           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 = expiring.call({ "state" => now["state"], "requestId" => rid, "number" => n }, live)
+            # "Why?": the case code stays on screen while it waits, and so does when the request expires.
             waiting["caseCode"] = bound["cc"] if bound["cc"]
             return issue.call(waiting, { "n" => n })
           end

data/lib/touchque/rails/guard.rb

@@ -37,6 +37,8 @@ module Touchque
     #
     # 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.
+    # enroll: false: a user with no phone gets 202 {"touchque": {"state": "enroll",
+    # "reason": "enrollment_off"}} instead of the linking QR.
     module Guard
       def self.included(base)
         base.extend(ClassMethods)
@@ -86,22 +88,29 @@ module Touchque
           request.env["touchque.approval"] = result[:approved]
           return
         end
-        Touchque::Guard.headers(result).each { |name, value| response.headers[name] = value }
-        render json: touchque_body(result, options[:error_body]), status: result[:status]
+        touchque_render(result, options[:error_body])
       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
+      # Renders a guard result that is not an approval as Touchque::Guard.response gives it
+      # (render sets the JSON content type).
+      def touchque_render(result, error_body)
+        status, headers, body = Touchque::Guard.response(result, error_body: touchque_error_body(error_body))
+        headers.each { |name, value| response.headers[name] = value unless name == "content-type" }
+        render json: body, status: status
+      end
+
+      # error_body as a callable for Touchque::Guard.response: a proc runs in the controller,
+      # a Symbol names one of its methods.
+      def touchque_error_body(error_body)
+        return nil if error_body.nil?
 
-        Touchque::Guard.error_body(result, lambda { |refusal|
+        lambda do |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
       end
 
       def touchque_value(option)

data/lib/touchque/railtie.rb

@@ -10,9 +10,17 @@ module Touchque
   #   config.touchque.api_secret = "..."
   #   config.touchque.login = { domain: "acme.login.touchque.com", client_id: "...", client_secret: "..." }
   #   config.touchque.session_secret = "..."       # Touchque Login cookies; default: secret_key_base
+  #
+  # Touchque.logger defaults to Rails.logger, so the SDK's own problems (a guard without its
+  # keys, a failing error_body) reach your log. Set your own in an initializer (nil: none).
   class Railtie < ::Rails::Railtie
     config.touchque = ActiveSupport::OrderedOptions.new
 
+    # Before the app's config/initializers, which may set their own.
+    initializer "touchque.logger" do
+      Touchque.logger ||= ::Rails.logger
+    end
+
     initializer "touchque.configure" do |app|
       settings = app.config.touchque
       credentials = app.respond_to?(:credentials) ? (app.credentials.config[:touchque] || {}) : {}

data/lib/touchque/relay.rb

@@ -105,6 +105,9 @@ module Touchque
   #   get_user_id      (required) the signed-in user, for the signed-in routes.
   #   get_login_user   the user who passed YOUR first factor. STRONGLY RECOMMENDED: /login
   #                    and the offline routes then act for this user and ignore the body's.
+  #                    Without it /login never shows the linking QR: a user with no phone gets
+  #                    202 {touchque: {state: "enroll", reason: "enrollment_off"}}, as passkey
+  #                    registration does.
   #   rate_limit       { window_seconds:, per_ip: 20, per_user: 5, store: } or false.
   #   allow_offline_without_first_factor  let the offline routes trust the body's username.
   #   action_type      for /login and the offline routes (default LOGIN).
@@ -256,10 +259,12 @@ module Touchque
       end
     end
 
-    # A guard answer that is not an approval, with Guard.headers (no-store, Retry-After, X-Touchque-State / -Reason).
+    # A guard answer that is not an approval, as Guard.response gives it (no-store, Retry-After,
+    # X-Touchque-State / -Reason); the Rack relay adds the content type itself.
     def guard_response(result)
-      res = RelayResponse.new(result[:status], result[:body])
-      Guard.headers(result).each { |name, value| res.set_header(name, value) }
+      status, headers, body_json = Guard.response(result)
+      res = RelayResponse.new(status, JSON.parse(body_json))
+      headers.each { |name, value| res.set_header(name, value) unless name == "content-type" }
       res
     end
 

data/lib/touchque/testing.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "set"
+require_relative "../touchque"
+
+module Touchque
+  # Helpers for your app's tests (require "touchque/testing"; never in production code).
+  module Testing
+    # A Touchque client for your app's tests: no network, no API keys, no Node.js. It is a
+    # real Touchque::Client whose API calls are answered in memory, so the real guard runs:
+    # your routes answer exactly what they answer in production (202 and a token, then your
+    # action once approved), and your test plays the phone.
+    #
+    #   require "touchque/testing"
+    #
+    #   tq = Touchque::Testing::FakeTouchque.new.install # the default client (Touchque.client)
+    #   post "/transfers", params: { amount: 5 }, as: :json
+    #   assert_response 202
+    #   tq.approve                                        # the person approves on the phone
+    #   post "/transfers", params: { amount: 5 }, as: :json,
+    #                      headers: { "X-Touchque-Token" => response.parsed_body["token"] }
+    #   assert_response :success
+    #   tq.uninstall
+    #
+    # +linked+ (default true): every user has a phone linked, so a guarded route sends a
+    # push. unlink(user) gives that user the first-time QR instead; with linked: false only
+    # the users you link have one.
+    #
+    # The phone is yours to drive: approve, reject or expire the latest request (or one by
+    # its id), or set auto_approve to approve every request as it is made. +requests+ lists
+    # the approval requests ("id", "user", "type", "details", "referenceId", "status":
+    # PENDING / CONFIRMED / REJECTED / EXPIRED, "expiresAt": 30 s after it was made, answered
+    # on each status check), +calls+ every API call ("method", "path", "body"), in order.
+    #
+    # +number_match+: pushes ask for the number "47". +secret_ttl_ms+: how long a first-time
+    # QR works (5 minutes, like the API). The offline code is "ABCD123" and the time-based
+    # code "123456" (+offline_code+, +totp_code+).
+    #
+    # It answers the calls the step-up guard makes (approval requests, first-time linking,
+    # offline codes, silent sign-in checks) and defining action types, like the shared fake
+    # API the SDKs' own tests use. Any other call raises Touchque::APIError 404.
+    class FakeTouchque < Client
+      # The code the phone shows for an offline QR (X-Touchque-Code).
+      OFFLINE_CODE = "ABCD123"
+      # The time-based code (X-Touchque-Code-Type: totp).
+      TOTP_CODE = "123456"
+
+      NOT_INSTALLED = Object.new.freeze
+      private_constant :NOT_INSTALLED
+
+      # Approve every new request at once, as if the person tapped Approve straight away.
+      attr_accessor :auto_approve
+      # Ask for the number "47" on every push.
+      attr_accessor :number_match
+      # How long a first-time QR works, in ms.
+      attr_accessor :secret_ttl_ms
+      # The codes the fake accepts for an offline QR and as the time-based code.
+      attr_accessor :offline_code, :totp_code
+      # Whether users you did not link or unlink have a phone (the linked: option).
+      attr_reader :linked_by_default
+      # The approval requests made so far, oldest first.
+      attr_reader :requests
+      # Every API call so far: {"method", "path", "body"}, oldest first.
+      attr_reader :calls
+
+      def initialize(linked: true, auto_approve: false, number_match: false)
+        @lock = Monitor.new
+        @linked_by_default = linked
+        @auto_approve = auto_approve
+        @number_match = number_match
+        @secret_ttl_ms = 300_000
+        @offline_code = OFFLINE_CODE
+        @totp_code = TOTP_CODE
+        @requests = []
+        @calls = []
+        @linked = Set.new
+        @unlinked = Set.new
+        @pending = {}
+        @challenges = {}
+        @defined_types = {}
+        @seq = 0
+        @replaced = NOT_INSTALLED
+        # Signs the guard tokens only: nothing leaves the process.
+        super(api_key: "tq_fake_key", api_secret: "fake_secret", base_url: "http://localhost")
+      end
+
+      # ── the phone ──────────────────────────────────────────────────────
+
+      # +user+ has a phone linked (as if they scanned the first-time QR).
+      def link(user)
+        @lock.synchronize do
+          @linked << user
+          @unlinked.delete(user)
+          @pending.delete(user)
+        end
+        self
+      end
+
+      # +user+ has no phone linked: a guarded route shows them the first-time QR.
+      def unlink(user)
+        @lock.synchronize do
+          @unlinked << user
+          @linked.delete(user)
+          @pending.delete(user)
+        end
+        self
+      end
+
+      def linked?(user)
+        @lock.synchronize { @linked.include?(user) || (linked_by_default && !@unlinked.include?(user)) }
+      end
+
+      # The person approves on the phone: the latest request, or +request_id+.
+      # via: "WEBAUTHN" approves it with a passkey. Returns the request's id.
+      def approve(request_id = nil, via: "DEVICE")
+        @lock.synchronize do
+          request = pick(request_id)
+          request.merge!("status" => "CONFIRMED", "confirmedVia" => via)
+          request["id"]
+        end
+      end
+
+      # The person taps Reject: the latest request, or +request_id+.
+      def reject(request_id = nil)
+        @lock.synchronize do
+          request = pick(request_id)
+          request["status"] = "REJECTED"
+          request["id"]
+        end
+      end
+
+      # Nobody answered in time: the latest request, or +request_id+.
+      def expire(request_id = nil)
+        @lock.synchronize do
+          request = pick(request_id)
+          request["status"] = "EXPIRED"
+          request["id"]
+        end
+      end
+
+      # ── the default client ─────────────────────────────────────────────
+
+      # Makes this the default client (Touchque::Guard.default_client = self, so
+      # Touchque.client), which require_touchque, Touchque::Guard.run(nil, ...) and a relay
+      # given no client use, until uninstall.
+      # With a block: installed for the block only. Install it after your app configured
+      # Touchque: Touchque.configure drops it.
+      def install
+        @lock.synchronize do
+          @replaced = Touchque.instance_variable_get(:@client) if @replaced.equal?(NOT_INSTALLED)
+          Touchque::Guard.default_client = self
+        end
+        return self unless block_given?
+
+        begin
+          yield self
+        ensure
+          uninstall
+        end
+      end
+
+      # Puts back the default client that install replaced.
+      def uninstall
+        @lock.synchronize do
+          next if @replaced.equal?(NOT_INSTALLED)
+
+          Touchque::Guard.default_client = @replaced
+          @replaced = NOT_INSTALLED
+        end
+        self
+      end
+
+      private
+
+      def transport(**options)
+        Transport.new(self, **options)
+      end
+
+      def pick(request_id)
+        request = request_id ? find(request_id) : @requests.last
+        return request if request
+
+        raise ArgumentError, request_id ? "FakeTouchque: no approval request #{request_id}" : "FakeTouchque: no approval request yet"
+      end
+
+      def find(request_id)
+        @requests.find { |r| r["id"] == request_id }
+      end
+
+      # What the fake answers: [status, data].
+      def answer(method, path_with_query, body)
+        path = path_with_query.split("?", 2).first
+        @lock.synchronize do
+          @calls << { "method" => method, "path" => path, "body" => body }
+          ROUTES.each do |route_method, pattern, handler|
+            next unless route_method == method && (m = pattern.match(path))
+
+            return send(handler, body.is_a?(Hash) ? body : {}, *m.captures.map { |part| URI.decode_www_form_component(part) })
+          end
+          [404, { "error" => "FakeTouchque does not answer #{method} #{path}" }]
+        end
+      end
+
+      def login_request(body)
+        user = body["externalUsername"]
+        return [404, { "code" => "device_not_linked", "error" => "No linked device found for this user" }] unless linked?(user)
+
+        @seq += 1
+        number = number_match || body["requireNumberMatch"] == true ? "47" : nil
+        request = {
+          "id" => format("00000000-0000-4000-8000-%012d", @seq), "user" => user, "type" => body["type"],
+          "referenceId" => body["referenceId"], "details" => body["details"], "status" => "PENDING",
+          "consumed" => false, "challengeCode" => number, "confirmedVia" => nil,
+          "expiresAt" => Steps.iso_of(Util.now_ms + 30_000)
+        }
+        request.merge!("status" => "CONFIRMED", "confirmedVia" => "DEVICE") if auto_approve
+        @requests << request
+        [200, { "message" => "Request sent", "requestId" => request["id"], "challengeCode" => number,
+                "expiresAt" => request["expiresAt"], "caseCode" => "K7P-2QX" }]
+      end
+
+      def approval(request)
+        passkey = request["confirmedVia"] == "WEBAUTHN"
+        {
+          "externalUsername" => request["user"], "type" => request["type"], "referenceId" => request["referenceId"],
+          "details" => request["details"], "confirmedVia" => request["confirmedVia"],
+          "assurance" => request["status"] == "CONFIRMED" ? { "phishingResistant" => passkey, "method" => passkey ? "passkey" : "push" } : nil,
+          "provisional" => false, "reconfirmedAt" => nil, "revoked" => false, "revokeReason" => nil
+        }
+      end
+
+      def login_status(_body, request_id)
+        request = find(request_id)
+        return [404, { "code" => "not_found" }] unless request
+
+        # The request's expiry, as the API answers it on every status check.
+        [200, { "status" => request["status"], "consumed" => request["consumed"], "expiresAt" => request["expiresAt"] }.merge(approval(request))]
+      end
+
+      def login_consume(_body, request_id)
+        request = find(request_id)
+        return [404, { "code" => "not_found" }] unless request
+        unless request["status"] == "CONFIRMED"
+          return [409, { "code" => { "REJECTED" => "rejected", "EXPIRED" => "expired" }.fetch(request["status"], "not_approved") }]
+        end
+        return [409, { "code" => "already_used" }] if request["consumed"]
+
+        request["consumed"] = true
+        [200, { "consumed" => true, "requestId" => request["id"], "approvalProof" => nil }.merge(approval(request))]
+      end
+
+      def new_secret(user)
+        @seq += 1
+        expires = Util.now_ms + secret_ttl_ms
+        @pending[user] = expires
+        { "secret" => "S#{@seq}", "qrCodeDataUrl" => "data:image/png;base64,QR#{@seq}-#{user}", "externalUsername" => user,
+          "expiresAt" => Steps.iso_of(expires), "ttlMs" => secret_ttl_ms, "recoveryCodes" => ["r#{@seq}"] }
+      end
+
+      def generate_secret(body)
+        user = body["externalUsername"]
+        return [409, { "error" => "already linked" }] if linked?(user)
+        return [409, { "error" => "Secret already generated" }] if @pending.key?(user)
+
+        [200, new_secret(user)]
+      end
+
+      # Like the API: a reset unlinks the phone (the guard only resets a user it found not linked).
+      def reset_secret(body)
+        user = body["externalUsername"]
+        @unlinked << user
+        @linked.delete(user)
+        [200, { "success" => true }.merge(new_secret(user))]
+      end
+
+      def get_user(_body, user)
+        linked = linked?(user)
+        return [404, { "error" => "not found" }] if !linked && !@pending.key?(user)
+
+        [200, { "externalUsername" => user, "deviceId" => linked ? "dev-1" : nil, "used" => linked, "frozen" => false, "device" => nil }]
+      end
+
+      def offline_challenge(body)
+        request_id = body["requestId"]
+        follows = request_id ? find(request_id) : nil
+        return [404, { "error" => "request_not_found" }] if request_id && follows.nil?
+        return [409, { "error" => "request_rejected" }] if follows && follows["status"] == "REJECTED"
+
+        @seq += 1
+        challenge_id = "ch-#{@seq}"
+        @challenges[challenge_id] = { "user" => body["externalUsername"], "type" => body["type"], "used" => false, "requestId" => request_id }
+        out = { "challengeId" => challenge_id, "qr" => "TQ2.fake", "qrDataUrl" => "data:image/png;base64,OFFLINE",
+                "expiresAt" => Steps.iso_of(Util.now_ms + 120_000), "expiresInSeconds" => 120, "totpAvailable" => true }
+        number = follows&.fetch("challengeCode", nil) || (body["requireNumberMatch"] == true ? "47" : nil)
+        out["challengeCode"] = number if number
+        [200, out]
+      end
+
+      def rejected?(request_id)
+        request = request_id ? find(request_id) : nil
+        request ? request["status"] == "REJECTED" : false
+      end
+
+      def offline_verify(body)
+        challenge = @challenges[body["challengeId"]]
+        return [404, { "approved" => false, "reason" => "unknown_challenge" }] unless challenge
+        return [410, { "approved" => false, "reason" => "used" }] if challenge["used"]
+        return [410, { "approved" => false, "reason" => "request_rejected" }] if rejected?(challenge["requestId"])
+        return [401, { "approved" => false, "reason" => "invalid_code", "attemptsLeft" => 4 }] unless body["code"] == offline_code
+
+        challenge["used"] = true
+        [200, { "approved" => true, "challengeId" => body["challengeId"], "externalUsername" => challenge["user"], "type" => challenge["type"] }]
+      end
+
+      def offline_totp_verify(body)
+        return [410, { "approved" => false, "reason" => "request_rejected" }] if rejected?(body["requestId"])
+        return [401, { "approved" => false, "reason" => "invalid_code" }] unless body["code"] == totp_code
+
+        [200, { "approved" => true, "externalUsername" => body["externalUsername"] }]
+      end
+
+      # Silent sign-ins: the fake always asks the phone.
+      def risk_check(body)
+        reason = if body["browserProof"]
+                   { "code" => "new_browser", "text" => "This browser has not been approved on the phone for this account" }
+                 else
+                   { "code" => "no_browser_key", "text" => "No device-bound browser key was presented" }
+                 end
+        [200, { "prompt" => true, "reasons" => [reason], "assurance" => "normal", "silentMode" => "enforce", "caseCode" => "CHK-2QX" }]
+      end
+
+      def define_action_type(body)
+        @seq += 1
+        defined = { "id" => "at-#{@seq}", "type" => body["type"], "name" => body["name"], "description" => body["description"] || "",
+                    "critical" => body["critical"] ? true : false, "active" => true }
+        @defined_types[body["type"]] = defined
+        [200, defined]
+      end
+
+      def list_action_types(_body)
+        [200, @defined_types.values]
+      end
+
+      # What the fake answers: method, path pattern, handler (body, path parts).
+      ROUTES = [
+        ["POST", %r{\A/login/request\z}, :login_request],
+        ["GET", %r{\A/login/status/([^/]+)\z}, :login_status],
+        ["POST", %r{\A/login/([^/]+)/consume\z}, :login_consume],
+        ["POST", %r{\A/auth/generate-secret\z}, :generate_secret],
+        ["POST", %r{\A/auth/secret/reset\z}, :reset_secret],
+        ["GET", %r{\A/users/([^/]+)\z}, :get_user],
+        ["POST", %r{\A/offline/challenge\z}, :offline_challenge],
+        ["POST", %r{\A/offline/verify\z}, :offline_verify],
+        ["POST", %r{\A/offline/totp/verify\z}, :offline_totp_verify],
+        ["POST", %r{\A/risk/check\z}, :risk_check],
+        ["POST", %r{\A/action-types\z}, :define_action_type],
+        ["GET", %r{\A/action-types\z}, :list_action_types]
+      ].freeze
+      private_constant :ROUTES
+
+      # The HTTP of a FakeTouchque: every call goes to the fake as JSON, and comes back as
+      # JSON or as the error the real client raises.
+      class Transport < HTTP
+        def initialize(fake, **options)
+          @fake = fake
+          super(**options)
+        end
+
+        private
+
+        def send_request(method, path_with_query, body, raw: false)
+          sent = body.nil? ? {} : JSON.parse(Util.json(Util.stringify(body)))
+          status, data = @fake.__send__(:answer, method, path_with_query, sent)
+          text = Util.json(data)
+          return text if raw && status < 300
+          raise APIError.for(status, JSON.parse(text)) if status >= 300
+
+          JSON.parse(text)
+        end
+      end
+      private_constant :Transport
+    end
+
+    # Another name for FakeTouchque.
+    FakeClient = FakeTouchque
+  end
+end

data/lib/touchque/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: touchque
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Touchque
@@ -52,6 +52,7 @@ files:
 - lib/touchque/resources/webhook.rb
 - lib/touchque/safe_approval.rb
 - lib/touchque/security_events.rb
+- lib/touchque/testing.rb
 - lib/touchque/util.rb
 - lib/touchque/version.rb
 homepage: https://touchque.com