touchque 5.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6955277b3bc3e32deb8f97a7d137f02f5d3517b7897801a47f2ea7450025459c
+  data.tar.gz: cbbe23f464baba65fc927cd7d34ec609be4bdc1a33d2841e07a53b1f66a0c61c
+SHA512:
+  metadata.gz: 89047ee9495e0d3f2871feda126bea65fc520db8a4300eb9e49a9c0e167e2a803c34407dbb052101c1104ddc03be71141dfa3bebb818319ebf3058bb74d4370e
+  data.tar.gz: 20ce50cfbc756507d749bc4c404755b74f561708bd7c88f8845d77a4a11115f5df2226b1e2c61a3c324b8f1f908440badc97def0a783567c8a4275d11d776afb

data/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+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.0.0] — 2026-11-12
+
+### Breaking
+- **Every name is spelled Touchque instead of TouchQue.** Code that uses the old names must be updated; nothing else changes. Old → new:
+  - The module: `TouchQue` → `Touchque` (`TouchQue.client`, `.configure`, `.logger`, `.replay_cache`, `.login_options`, `.login_secret` and `.hosted_login` → `Touchque.client`, `Touchque.configure`...).
+  - The client class: `TouchQue::Client` → `Touchque::Client`.
+  - The error classes: `TouchQue::Error`, `TouchQue::APIError`, `TouchQue::NetworkError`, `TouchQue::RejectedError`, `TouchQue::TimeoutError`, `TouchQue::PasskeyRequiredError`, `TouchQue::ConfigError`, `TouchQue::WebhookSignatureError`, `TouchQue::WebhookReplayError`, `TouchQue::ApprovalError`, `TouchQue::ApprovalMismatchError`, `TouchQue::FeatureError` (and `FeatureNotInPlanError`, `FeatureReadOnlyError`, `FeatureOffError`), `TouchQue::HostedLoginError`, `TouchQue::MyAccountError`, `TouchQue::McpAuthError`, `TouchQue::IdJagError`, `TouchQue::AgentCardError` and `TouchQue::SecurityEventError` → `Touchque::Error`, `Touchque::APIError`, `Touchque::NetworkError` and so on.
+  - Every other class and module under it: `TouchQue::Resources::*`, `TouchQue::Guard`, `TouchQue::Agent`, `TouchQue::OrgAgent`, `TouchQue::McpAuth`, `TouchQue::HostedLogin`, `TouchQue::SafeApproval`, `TouchQue::CodeReply`... → `Touchque::Resources::*`, `Touchque::Guard`, `Touchque::Agent`...
+  - Rails: `TouchQue::Rails::Guard`, `TouchQue::Rails::Webhook`, `TouchQue::Rails::HostedLogin`, `TouchQue::Rails.login_routes` and `TouchQue::SessionsController` → `Touchque::Rails::Guard`, `Touchque::Rails::Webhook`, `Touchque::Rails::HostedLogin`, `Touchque::Rails.login_routes` and `Touchque::SessionsController`. `login_routes`' default controller is now `"touchque/sessions"` (was `"touch_que/sessions"`, the route name Rails derived from the old class name); change it if you passed it yourself.
+  - Rack: `TouchQue::Rack::Relay` → `Touchque::Rack::Relay`.
+  - The guard's header names (`Touchque::Guard::TOKEN_HEADER`, `OFFLINE_HEADER`, `CODE_HEADER`, `CODE_TYPE_HEADER`, `BROWSER_HEADER`): `X-TouchQue-Token`, `X-TouchQue-Offline`, `X-TouchQue-Code`, `X-TouchQue-Code-Type`, `X-TouchQue-Browser` → `X-Touchque-Token`, `X-Touchque-Offline`, `X-Touchque-Code`, `X-Touchque-Code-Type`, `X-Touchque-Browser`. HTTP header names are case-insensitive, so servers are unaffected.
+  - The SDK's log lines start with `[Touchque]` (was `[TouchQue]`) and its error messages with `Touchque:`.
+  - The same as before: the gem name `touchque`, `require "touchque"`, `config.touchque` and `credentials.touchque`, the `/touchque` mount path, the cookies, the JSON the API sends and receives, the `TQ_*` environment variables, and the signed EIP-712 type string `TouchQueGovernance(...)` that the Safe Guard contract hashes.
+
+### Changed
+- The README has an "Action types" section: define a type once (dashboard → Developers → Action types, or from code); the guard answers 500 `misconfigured` for an undefined name and 403 `action_disabled` for one turned off.
+
+## [4.2.0] — not published (these changes ship in 5.0.0)
+
+### Security
+- **The offline approval-token check refuses another workspace's token.** `GET /agents/jwks.json` is one key set for every Touchque workspace, and the check used to compare `aud` only when you passed an audience, so a token Touchque signed for someone else's workspace (their own phone, any person's name, any details) could pass your executor. Now:
+  - `agents.verify_approval_token(token, audience: nil, ...)` uses this workspace's own audience by default: `agents.approval_audience` asks `GET /agents/approval-audience` once (`touchque:workspace:<id>`) and keeps it.
+  - `ApprovalToken.verify_with(token, jwks, audience:, ...)` requires the audience. A missing or empty one throws Touchque::ApprovalMismatchError (`audience is required`).
+  - A token without `aud` is refused (`the approval token names no workspace`), as is one for another workspace (`the approval token is for another workspace`).
+  - Breaking for callers of the low-level function who passed no audience: pass agents.approval_audience's value.
+  - `redeemApproval` was already safe: Touchque compares `aud` with your workspace there.
+
+### Added
+- **`device_risk.search_events(...)`: search your workspace's Device risk identifications**, newest first, one page at a time (`GET /device-risk/events`): `from:`/`to:` (7 days by default, at most 90, within your retention), `signal:`, `step_up:`, `kind:`, `origin:`, `ip:` (an address or a CIDR range; never returned), `account:`, `visitor_id:`, `request_id:`, `limit:` (1 to 100) and the opaque `cursor:` from the previous page's `"nextCursor"`.
+- `device_risk.check` returns `"engine"` (String or nil): the engine's state for this check; `"unavailable"` when the risk engine could not be reached and the verdict is a safe default (`"stepUp"` true), so an outage can be told apart from risk.
+- **`webauthn.primary_availability`: is passkey sign-in on for your workspace?** `GET /webauthn/authenticate/primary/availability` answers `{ "enabled" => bool, "userVerification" => "required" | "preferred" | nil }`. Ask before your sign-in page shows its passkey button and passkey autofill; when it is off, `primary_options` answers 403 `passwordless_login_disabled`.
+- `agents.get_workspace_policy`, the name every other Touchque SDK uses, as an alias of `agents.workspace_policy` (which stays; `set_workspace_policy` was already there).
+- **Webhook events of Never Locked Out and the help desk**, the names the API sends: `Webhook::EVENT_RECOVERY_STARTED`, `EVENT_RECOVERY_DEVICE_BOUND`, `EVENT_RECOVERY_COOLING`, `EVENT_RECOVERY_COMPLETED`, `EVENT_RECOVERY_VETOED`, `EVENT_RECOVERY_EXPIRED`, `EVENT_RECOVERY_FAILED` and `EVENT_ASSIST_OPENED`, `EVENT_ASSIST_ENDED`, `EVENT_ASSIST_CHECK_PASSED`, `EVENT_ASSIST_CHECK_FAILED`, `EVENT_ASSIST_UNFROZEN`, `EVENT_ASSIST_CLAIM_CONFIRMED`, `EVENT_ASSIST_CLAIM_UNVERIFIED`.
+- `SecurityEvents.poll` sends `Accept: application/json`, like the Node SDK (it sent Net::HTTP's `*/*`).
+- README: "Shared Signals (security events from Touchque SSO)", verifying a pushed SET and polling; tests for the keys found through `/.well-known/ssf-configuration` and for a poll, against a local transmitter.
+- **Shared Signals: receive the security events an identity provider sends after sign-in.** Touchque SSO sends Security Event Tokens (OpenID Shared Signals Framework 1.0) for an organization's members to the receivers its admin adds (Organization > Continuous access): CAEP `session-revoked`, `credential-change`, `device-compliance-change`, RISC `account-disabled`, `credential-compromise`; `txn` carries the case code of Touchque's decision. `Touchque::SecurityEventVerifier.new(issuer:, audience:, jwks_uri:, jwks:, clock_skew:).verify(token)` returns `{ "jti", "issuer", "audience", "issued_at", "txn", "subject", "type", "name", "claims" }` or raises `Touchque::SecurityEventError` with the RFC 8935 code to answer in `error` (`invalid_request`, `invalid_key`, `invalid_issuer`, `invalid_audience`); `Touchque::SecurityEvents.poll(url:, token:, ack:, set_errs:, max_events:)` for poll delivery (RFC 8936); `SecurityEvents::TYPES`. The keys come from the issuer's `/.well-known/ssf-configuration`; a SET does not expire, so keep the jtis you handled. Tested against the shared vectors (`fixtures/security-event-vectors.json`).
+- **Safe Guard: Safe transactions approved on the approver's phone, for TouchqueSafeGuard.** `tq.safe_guard.request(external_username, type, safe_tx, reference_id:, expires_in:)` sends the raw transaction (the phone decodes it itself and signs with a key only its biometrics unlock), `status(request_id)` and `wait_for_approval(request_id)` hand back the 105-byte approval. `Touchque::SafeApproval.verify(target, approval, approver_key, purpose:, approver_index:, rows: | display_digest:, now:)` checks it the way the guard does, without trusting Touchque: the Safe transaction hash (EIP-712, Keccak-256 here) and the governance hash computed here, the 149-byte message, low `s`, the one-day expiry window, the P-256 signature. `SafeApproval.with_approvals(owner_signatures, approvals)` for `execTransaction`, `SafeApproval.schedule_call(safe, governance_hash, approvals)` for a governance change; `safe_tx_hash`, `governance_hash`, `message`, `display_digest`. Tested against the shared vectors (`fixtures/safe-guard-vectors.json`).
+
+### Fixed
+- An empty `reference_id` is no reference, as for the API: `login.request` no longer sends `"referenceId": ""`, and `complete` (and so the guard) no longer raises `ApprovalMismatchError` after using up an approval started with `reference_id: ""`.
+- The step-up guard (`Guard.run`, `require_touchque`, the relay's `/login`) answers the contract's 503 `unavailable` for any failure, an approval for another transaction included, instead of a bare 500. Every connection failure and garbled answer (`ENETUNREACH`, `EPIPE`, a bad status line...) now raises `Touchque::NetworkError`.
+- Transaction details are trimmed like the API trims them (JavaScript's trim: no-break and other Unicode spaces too), so `complete` and `ApprovalProof.verify` no longer refuse details that start or end with such a space.
+- `login.verify` passes `expires_in:` and `client_signals:` on to the request instead of dropping them.
+- `Touchque::Rack::Relay` loads on first use: the documented Sinatra / plain Rack mount works without Rails and without `require "touchque/rack/relay"`.
+- The relay answers 400 `invalid_credential_id` to `DELETE /passkey/credentials/{id}` with a malformed %-encoding instead of a 500.
+
+### Security
+- **Hosted login: an empty `iss` is refused too (RFC 9207).** `handle_callback` (and so the Rails `/callback`) already refused a callback whose `iss` names another issuer; one with an empty `iss=` now raises `issuer_mismatch` as well, before the code is exchanged. A callback without `iss` (a server that does not send it yet, or a nil value) is still accepted.
+- `inspect` (and `pp`) of `Touchque::Client`, its `webhook`, `HostedLogin` and `MyAccount` no longer show the API key, the API secret, the client secret or the access token.
+- `SafeApproval.verify` without `purpose:` accepts only an ordinary approval (`"approve"`). A schedule approval covers no Safe nonce or gas fields, so it is accepted only with `purpose: "schedule"`, never as permission to execute.
+- Touchque Login (`HostedLogin`, `MyAccount`) refuses a plaintext `http://` domain except on this machine (`localhost`, `127.0.0.1`, `::1`, `*.localhost`), like `base_url`: codes, PKCE verifiers, the client secret and tokens never travel in the clear.
+
+## [4.1.0] — not published (these changes ship in 5.0.0)
+
+### Added
+- **Device risk events like a device-intelligence event, without raw traits:** `deviceRisk.check` and `getEvent` answers carry `network`, `velocity` and `bot`: the address as the risk engine saw it (country, region, city, never coordinates; the operator; `type` isp, hosting or tor; `timezoneMismatch` when the browser's clock does not fit the address), the visitor's counts (accounts, sign-ups, countries, stored-id resets, identifications in the last hour and day) and one answer to "a bot?" (`detected`, `suspected` or `not_detected`, with reasons). The field the script tag fills may now carry its pointer summary after the requestId: pass it as it came.
+
+### Changed
+- **Silent by default.** Nothing goes to `$stderr` (`Kernel#warn`) on its own any more: the SDK's own problems (a misconfigured guard, a failed `on_challenge`, a relay error or a relay without `get_login_user`) go to `Touchque.logger` (`Touchque.logger = Rails.logger`); nil, the default, logs nothing.
+- `ApprovalMismatchError` no longer names the other person in its message.
+
+### Added
+- **A code typed back on the phone:** `tq.login.request(..., reply: { kind: "code", key:, channel:, target: })`; `Touchque::CodeReply.new_key` and `Touchque::CodeReply.open(private_key, request_id, ct)` open `status(id)["reply"]["ct"]`.
+- **Feature errors:** a feature your organization cannot use here (403 `feature_not_in_plan`, `feature_read_only`, `feature_off`) raises `FeatureNotInPlanError`, `FeatureReadOnlyError` or `FeatureOffError`, all `FeatureError` (`feature`, `feature_reason`) and still `APIError`.
+
+First release of the Ruby SDK, at the same surface as the Node, Python, PHP, Go and .NET SDKs 4.1.0.
+
+### Added
+- **Webhook events `DEVICE_RISK_SIGNAL` and `DEVICE_RISK_ALERT`** (`Webhook::EVENT_DEVICE_RISK_*`): a Device risk signal that asks for more (identifiers, signals and the engine's verdict, never a trait), and an alert rule of the workspace that went off. Signed like every event.
+- **Device risk in one line: `tq.device_risk.check(params[:touchque_request_id], event: "sign_in", external_username: email)`** with the script tag (`device.js`, `@touchque/web` 1.6.0), which fills that field. Pass it as it came: nil, empty, made up or expired is still a verdict (`report` missing, unknown, expired, invalid; the signal `device_identification_missing`, a number-matched step-up at most), never an exception. `Touchque::Resources::DeviceRisk::REPORTS`.
+- **Device risk: `tq.device_risk.check(request_id, event:, external_username:, client_ip:)` and `tq.device_risk.get_event(request_id)`** (a paid add-on; 409 `device_risk_off` until the workspace turns it on), and `device_risk_request_id:` (or `device_risk:`) on `login.request` and `risk.check`. The page's requestId comes from `@touchque/web` `deviceRisk.identify`. Every signal only ever asks for more (`"stepUp"`, never a refusal); signals start in shadow.
+- **Pairing a browser by QR code: `tq.qr_pairings`.** `create(key_thumbprint, client_ip:, user_agent:, browser:, os:, ttl_seconds:)` registers a pairing for the browser key your page holds (`@touchque/web` `browserKey.thumbprint()`) and returns `"uri"` (`touchque://pair-browser?...`) to show as a QR code; the nonce in it stays with you (Touchque keeps its hash). `get(pairing_id)` says who scanned it and how near the phone was (`"proximity"`), `refuse(pairing_id, reason:, message:)` tells the phone why your own checks said no. `login.request(..., qr_pairing:)` asks the phone that scanned, once, with number matching. `Resources::QrPairings.uri`, `REFUSAL_REASONS`.
+- **Actions: the `agent.approval` trigger**, before an AI agent's request reaches the phone (`trigger: "agent.approval"`); only tightening counts: `api.deny`, `api.requirePasskey`, `api.stepUp`. See [Actions](https://support.touchque.com/actions).
+- **Webhook reason `user_blocked_agent`** (`Webhook::REASON_USER_BLOCKED_AGENT`): the person rejected an AI agent's request with Block this agent on their phone; the agent may not ask them again, and 2FA is not frozen. `agents.list_blocks` can return the block reason `"phone"`.
+- Request options and resources at the 4.1.0 surface: `challenge_digits:`, `expires_in:`, `client_signals:`, `security_changes:`, `destination:` and `locale:` on login requests; `client_signals:` on risk checks; the linked phone's posture on `auth.get_user`; `offline.totp_verifiers` + `Offline.match_totp_verifier` for a Touchque outage; Touchque Login email and SMS providers (`identity.set_delivery`) and attack protection; Mobile SDK settings with your own APNs key / FCM service account, `androidCerts` and `mobile.test_push`.
+- **AI agents: events for a SIEM.** `agents.list_events(after:, since:, limit:)`: the workspace's agent events (`AGENT_*`, `AGENTS_*`) oldest first, each with its agent, person, approval and case code; keep `"next"` and pass it as `after:`.
+- **AI agents: the workspace's policy and a passkey line.** `agents.workspace_policy` / `set_workspace_policy(policy)`: every agent's floor (an agent's own policy can only be stricter, field by field). `"requirePasskeyAbove" => { "TRY" => "10000.00" }` in any policy: over it the person approves with a passkey on your page (`"requiresPasskey"` on the approval), never on the phone or with a mandate; a background request gets 409 `interactive_required`. `Webhook::EVENT_AGENT_WORKSPACE_POLICY_CHANGED`. A second approver who answers sooner than a person can gets no token (status `blocked`, reason `inhuman_approval`).
+- **Touchque Login: the approving app's name and custom-domain-only sign-in.** `identity.set_approver_app_name(name)`: the phone app the hosted pages tell customers to approve on ("Approve on the Acme app"; `nil` = your brand when the Mobile SDK is set up, else Touchque). `identity.set_custom_domain_only(true)`: serve sign-in only on the primary custom domain ({slug}.login.touchque.com redirects page loads there and refuses other calls; needs a verified primary domain with a working certificate). `identity.check_domain_certificate(domain_id)`: the domain's certificate at the sign-in edge now (`certificate`: pending, active or error).
+- **Cross App Access (ID-JAG) and A2A agent cards.** `CrossAppAccess.request_id_jag` trades a member's ID token for an ID-JAG at the organization's identity provider, `redeem_id_jag` trades it for an access token at the other service (jwt-bearer); `IdJagVerifier` checks one at your own authorization server (typ, issuer, single audience, client, expiry, used once; `first_use` for a shared store). `AgentCard.verify` checks an A2A card's signatures (JWS over the RFC 8785 canonical card; `jku` only on the card's host or `trusted_jku_hosts`), `sign`, `canonical_json`.
+- **`Touchque::Client`** (Ruby 3.1+, standard library only): `auth`, `login` (request, status,
+  `verify` with an `on_challenge` block, `consume`, `report_fraud`, recovery codes), `webauthn`,
+  `offline` (QR and typed codes, outage verifiers), `risk` (silent sign-ins), `action_types`
+  (Second Thought questions), `actions` (Touchque Actions and their secrets), `recovery` (Never
+  Locked Out), `assist` (help desk), `agents` (with the token vault, mandates, blocks, the kill
+  switch, approval tokens), `identity` (the Touchque Login Management API), `mobile` (the Mobile
+  SDK's server side, `push_from_webhook`) and `webhook` (signature, timestamp window, replay cache).
+- `start` / `check` / `complete` and `Touchque::Guard.run`: the two-phase step-up contract shared
+  by every Touchque server SDK, with offline codes, silent sign-ins, Vishing Shield, Mirror Alarm
+  canaries and "Why?" case codes.
+- `Touchque::RelayHandler` and `Touchque::Rack::Relay`: the routes `@touchque/web` calls, with rate limits.
+- `Touchque::ApprovalProof`, `ApprovalToken`, `AgentKeys` (ES256 and EdDSA), `Touchque::Agent`
+  (private_key_jwt + DPoP), `Touchque::OrgAgent` (Touchque SSO agents) and `Touchque::McpAuth`.
+- `Touchque::HostedLogin` (Touchque Login OpenID Connect client) and `Touchque::MyAccount`;
+  `Touchque::LoginSession` (encrypted, chunked cookies, readable by the Node SDK's sealSession).
+- **Rails**: a Railtie (`config.touchque`, credentials), `Touchque::Rails::Guard`
+  (`require_touchque`), `Touchque::Rails::Webhook` (`verify_touchque_webhook`),
+  `Touchque::Rails::HostedLogin` (`/login`, `/callback`, `/logout`, `require_touchque_sign_in`)
+  and `Touchque::Rails.login_routes`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Touchque
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,383 @@
+# touchque (Ruby)
+
+The official Ruby server SDK for [Touchque](https://touchque.com): push approvals with number
+matching, passkeys, silent sign-ins, offline codes, verified webhooks, Touchque Actions, AI agent
+approvals, Touchque Login (hosted sign-in and the Management API) and the server side of the
+Mobile SDK. Rails integration included (a Railtie and controller concerns), plus a Rack relay for
+Sinatra and any Rack app.
+
+Ruby 3.1+, no runtime dependencies beyond the standard library (`net/http`, `openssl`, `json`).
+
+📘 Full docs: **[support.touchque.com](https://support.touchque.com)**
+
+## Install
+
+```ruby
+# Gemfile
+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):
+
+```bash
+export TQ_API_KEY=tq_auth_your_key
+export TQ_API_SECRET=your_api_secret
+```
+
+The secret signs every request: it belongs on your server only, never in a browser or an app.
+
+```ruby
+tq = Touchque.client                                             # from the environment, shared
+tq = Touchque::Client.new(api_key: "tq_...", api_secret: "...")   # explicit
+```
+
+In Rails the Railtie reads `config.touchque` (or `credentials.touchque`, then the environment):
+
+```ruby
+# config/application.rb
+config.touchque.api_key = Rails.application.credentials.dig(:touchque, :api_key)
+config.touchque.api_secret = Rails.application.credentials.dig(:touchque, :api_secret)
+```
+
+## Quick start (Rails)
+
+One line per protected action:
+
+```ruby
+class TransfersController < ApplicationController
+  include Touchque::Rails::Guard
+  require_touchque "SEND_MONEY", only: :create,
+                   details: -> { { "Amount" => params.require(:amount), "To" => params.require(:to) } }
+
+  def create
+    touchque_approval   # only reached once the user approved on their phone
+  end
+end
+```
+
+Until the user approves on their phone the action answers
+**`202 {"touchque": step, "token": "..."}`**. Your page shows `step` in its own design (the
+matching number, or a QR code the first time the user links the app) and sends the same request
+again with header `X-Touchque-Token: <token>`; [`@touchque/web`](https://www.npmjs.com/package/@touchque/web)
+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`.
+
+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] }`.
+
+**The end user's address.** The risk checks (Tor, location, impossible travel) and the location
+shown on the phone use `request.remote_ip`: configure `config.action_dispatch.trusted_proxies`
+behind a load balancer.
+
+## Action types
+
+`"SEND_MONEY"` above is an action type: one kind of approval, with the title the phone shows and
+whether it is critical. Define each one once, in the dashboard (**Developers → Action types**)
+or from code:
+
+```ruby
+tq.action_types.define("SEND_MONEY", name: "Send money", critical: true)
+```
+
+The guard refuses what is not ready. A name that is not defined is a setup error
+(`Touchque::ConfigError`, "Unknown action …"): the guard answers 500 with `reason: "misconfigured"`. A type
+turned off in the dashboard answers 403 with `reason: "action_disabled"`, which stops that kind of
+approval at once, without a deploy.
+
+## The three primitives (any framework)
+
+```ruby
+step = tq.start("SEND_MONEY", "jane@acme.com", details: { "Amount" => "250 EUR" })
+# step["state"]: waiting (show step["number"]) | enroll (show step["enroll"]["qrCodeDataUrl"]) | passkey_required | blocked | frozen | rate_limited
+now = tq.check(step["requestId"])
+approval = tq.complete(step["requestId"], "jane@acme.com", "SEND_MONEY", details: { "Amount" => "250 EUR" })
+# 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
+contract for Sinatra, Hanami or plain Rack.
+
+## Waiting in one call
+
+```ruby
+result = tq.login.verify("jane@acme.com", type: "LOGIN", client_ip: request.remote_ip, user_agent: request.user_agent) do |c|
+  # Number matching: show the number now; the phone asks for it.
+  notify("Pick #{c["challengeCode"]} on your phone") if c["challengeCode"]
+end
+```
+
+`verify` raises `Touchque::RejectedError`, `Touchque::TimeoutError` or
+`Touchque::PasskeyRequiredError` (`reason` "policy": approve with a passkey; "step_up": the user
+tapped Approve during a call and the request now waits for a passkey).
+
+## Relay routes for `@touchque/web`
+
+```ruby
+# config/routes.rb
+mount Touchque::Rack::Relay.new(
+  get_user_id: ->(req) { req.session["user_email"] },
+  # The user who already passed your password step. Binds /login and the offline routes to them.
+  get_login_user: ->(req) { req.session["password_verified_user"] },
+  on_authenticated: ->(req, response, info) { req.session["user_email"] = info["externalUsername"] },
+  silent_sign_in: true   # a known browser with nothing new skips the push
+) => "/touchque"
+```
+
+Routes: `POST /login`, `/enroll/start`, `GET /enroll/status`, `/offline/challenge|verify|totp`,
+`/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.
+
+## Webhooks
+
+```ruby
+class TouchqueWebhooksController < ActionController::API
+  include Touchque::Rails::Webhook
+  verify_touchque_webhook
+
+  def create
+    EndSession.call(touchque_webhook["requestId"]) if touchque_webhook["event"] == Touchque::Resources::Webhook::EVENT_APPROVAL_REVOKED
+    head :ok
+  end
+end
+```
+
+The signature (your API secret over the canonical JSON), the signed timestamp (5 minutes) and the
+`jti` are checked first: a bad one answers 401, a replay 200 without running your action again.
+`Touchque.replay_cache` is in-process by default; with several Puma workers or hosts set one over
+Redis (`check_and_set(jti, ttl_seconds)` with `SET NX EX`). Anywhere else:
+`tq.webhook.verify(raw_body, signature_header, replay_cache: cache)`.
+
+## Silent sign-ins
+
+```ruby
+risk = tq.risk.check(user, browser_proof: request.headers["X-Touchque-Browser"], client_ip: request.remote_ip)
+sign_in(user) if risk["prompt"] == false   # a known browser, nothing new: no push
+```
+
+Fails closed: only an answer of exactly `prompt: false` skips the phone. `tq.risk.browsers(user)`
+lists a user's known browsers; `forget_browsers(user)` forgets them (after a password reset).
+
+## Passkeys, offline codes, recovery, help desk
+
+- `tq.webauthn`: registration, second factor and passwordless sign-in options/verify, list and delete passkeys.
+- `tq.offline`: QR challenge and typed codes with the phone offline; `totp_verifiers` +
+  `Touchque::Resources::Offline.match_totp_verifier` check time-based codes while Touchque is unreachable.
+- `tq.recovery` (Never Locked Out): vouchers, `start` (show `bindUri` as a QR), `status`, `veto`.
+- `tq.assist` (help desk): `open`, `verify` (a 2-digit code the agent reads to the person), `spend`, `unfreeze`, `end`.
+- `Touchque::ApprovalProof.verify(proof, request_id:, type:, details:, expected_public_key:)`: the
+  phone's own signature over what it showed ("what you see is what you sign").
+
+## Touchque Actions
+
+```ruby
+tq.actions.deploy("night-alert", trigger: "approval.decided",
+                  template: { id: "alert", params: { channel: "slack", when: { countries: ["TR"] } } })
+replay = tq.actions.dry_run(trigger: "login.request", code: code, limit: 500)
+```
+
+Plus `test`, `rollback`, `logs`, `metrics`, `templates`, `secrets`. Action code is JavaScript run
+by Touchque in a sandbox, whatever language your server is in. Action types:
+`tq.action_types.define("SEND_MONEY", name: "Send money", critical: true)`.
+
+## AI agents
+
+Your server registers agents (public key only) and checks their approvals; the agent signs in with its own key:
+
+```ruby
+keys = Touchque::AgentKeys.generate                   # where the agent runs; "ES256" or "EdDSA"
+agent = tq.agents.create("Invoice bot", ["PAY_INVOICE"], public_key: keys["publicJwk"])
+
+# The agent (TQ_AGENT_ID, TQ_AGENT_KEY): private_key_jwt + DPoP, never your API key.
+bot = Touchque::Agent.new
+approved = bot.require_approval("ayse@acme.com", "PAY_INVOICE", [payment]) { |s| say "Type #{s["challengeCode"]} on your phone" }
+
+# Your server, right before it pays:
+tq.agents.redeem_approval(approved["approvalToken"], user: "ayse@acme.com", authorization_details: payment)
+```
+
+Also: mandates (`request_mandate`), the token vault (`tq.agents.vault`, `bot.get_connection_token`),
+policies, blocks, the kill switch, offline token checks (`verify_approval_token`).
+`Touchque::OrgAgent` is an organization's agent on Touchque SSO (DPoP tokens for one app, token
+exchange, CIBA, the token vault, shared accounts; GitHub Actions and Kubernetes tokens instead of
+a stored key). `Touchque::McpAuth` protects an MCP server whose authorization server is Touchque SSO.
+
+### Cross App Access (ID-JAG) and A2A agent cards
+
+An organization's identity provider (Touchque SSO) can let one of its apps reach another service for a member with no consent screen (Cross App Access, ID-JAG, an open IETF draft): the app trades the member's ID token for an ID-JAG, then the ID-JAG for an access token at the other service. If you run an authorization server, the verifier checks an ID-JAG (issuer, single audience, your client, expiry, `typ`) and uses it once. Before your agent trusts another agent's A2A card, check its signatures (A2A 1.0 §8.4: JWS over the RFC 8785 canonical card); keys named by `jku` are only fetched from the card's own host or hosts you trust.
+
+```ruby
+jag = Touchque::CrossAppAccess.request_id_jag(issuer: "https://sso.touchque.com", client_id: client_id, client_secret: secret,
+                                              id_token: id_token, audience: "https://auth.files.example")
+tokens = Touchque::CrossAppAccess.redeem_id_jag(token_endpoint: "https://auth.files.example/token", client_id: "acme",
+                                                client_secret: files_secret, assertion: jag["assertion"])
+
+# Your own authorization server (jwt-bearer grant):
+claims = Touchque::IdJagVerifier.new(issuer: "https://sso.touchque.com", audience: "https://auth.files.example")
+                                .verify(params[:assertion], client_id: authenticated_client_id)
+
+Touchque::AgentCard.verify(card_json, card_url: "https://agent.example/.well-known/agent-card.json")
+```
+
+## Shared Signals (security events from Touchque SSO)
+
+When something happens to a member's account after sign-in (sessions revoked, credentials changed or compromised, a device out of compliance, the account disabled), Touchque SSO sends a Security Event Token (OpenID Shared Signals Framework 1.0) to the receivers the organization's admin adds (Organization > Continuous access). Your app ends the person's sessions or asks them to sign in again. The verifier reads the keys from the issuer's `/.well-known/ssf-configuration` and checks the signature, `typ`, issuer, audience and the one event. A SET does not expire: keep the `jti`s you handled and skip a repeat.
+
+```ruby
+SSF = Touchque::SecurityEventVerifier.new(issuer: "https://sso.touchque.com", audience: "https://app.example.com")
+
+# Push (RFC 8935): the SET is the request body (application/secevent+jwt).
+def create
+  event = SSF.verify(request.raw_post)   # "name": session-revoked, credential-change, account-disabled...
+  end_sessions_of(event["subject"]["email"]) if event["name"] == "session-revoked"
+  head :accepted
+rescue Touchque::SecurityEventError => e
+  render json: { err: e.error, description: e.message }, status: e.error == "temporarily_unavailable" ? 503 : 400
+end
+
+# Poll (RFC 8936): acknowledge what you handled on the next call.
+ack = []
+loop do
+  out = Touchque::SecurityEvents.poll(url: poll_url, token: stream_token, ack: ack, max_events: 50, return_immediately: true)
+  ack = out["sets"].map do |jti, set|
+    handle(SSF.verify(set))
+    jti
+  end
+  break if ack.empty? && !out["more_available"]
+end
+```
+
+`verify` returns `"jti"`, `"issuer"`, `"audience"`, `"issued_at"`, `"txn"` (the case code of Touchque's decision), `"subject"`, `"type"`, `"name"` and `"claims"`, or raises `Touchque::SecurityEventError` whose `error` is the RFC 8935 code to answer (`invalid_request`, `invalid_key`, `invalid_issuer`, `invalid_audience`; `temporarily_unavailable` when the issuer's keys could not be read). Report a SET you refuse while polling with `set_errs: { jti => { "err" => e.error, "description" => e.message } }`.
+
+## Touchque Login (hosted sign-in)
+
+```ruby
+# config/application.rb
+config.touchque.login = { domain: "acme.login.touchque.com", client_id: "...", client_secret: "...",
+                          scope: "openid profile email offline_access" }
+
+# config/routes.rb
+Touchque::Rails.login_routes(self)        # GET /login, /callback, /logout
+
+class AccountController < ApplicationController
+  include Touchque::Rails::HostedLogin
+  before_action :require_touchque_sign_in
+  def show = render(json: touchque_session["user"])
+end
+```
+
+The session lives in encrypted cookies (AES-256-GCM, split when large, no session store needed;
+keyed from `config.touchque.session_secret` or `secret_key_base`) and is refreshed before the
+access token expires. `Touchque::HostedLogin` is the OpenID Connect client underneath (PKCE, ID
+and access token checks, refresh, token exchange, CIBA, the token vault, client credentials,
+logout); your API checks access tokens with `verify_access_token(token, audience:, required_scopes:)`.
+`login.my_account(access_token)` is the customer's own account API. The Management API is
+`tq.identity` (users, roles, organizations, apps, connections, imports and exports, attack
+protection, email and SMS providers).
+
+## Mobile SDK (your own app approves)
+
+```ruby
+e = tq.mobile.create_enrollment(user_id)                          # the app spends e["enrollmentToken"]
+push = Touchque::Resources::Mobile.push_from_webhook(event)        # a MOBILE_PUSH webhook → APNs payload / FCM data
+```
+
+Or give Touchque your APNs key / FCM service account (`update_settings(apns:, fcm:)`) and it pushes for you.
+
+## Pairing a browser by QR code
+
+Your page shows a QR code, the person scans it with the Touchque app, and the phone that scanned is the one asked to approve, with number matching. Your page sends the thumbprint of its browser key (`@touchque/web` `browserKey.thumbprint()`); the nonce in the QR never leaves your server (Touchque keeps its hash).
+
+```ruby
+p = tq.qr_pairings.create(key_thumbprint, client_ip: request.remote_ip, user_agent: request.user_agent)
+# show p["uri"] (touchque://pair-browser?...) as a QR code; poll:
+now = tq.qr_pairings.get(p["pairingId"])            # waiting -> scanned -> confirmed
+tq.login.request(now["externalUsername"], qr_pairing: p["pairingId"]) if now["state"] == "confirmed"
+# or: tq.qr_pairings.refuse(p["pairingId"], reason: "device_not_approved", message: "Ask IT to approve this computer.")
+```
+
+`get` says `scanned` / `confirmed` once a phone holding one of your users' accounts read it (with `proximity`: same network, same country), `reported` when the person said someone told them to scan it (their 2FA freezes). `refuse` tells the phone why your own checks said no.
+
+## A code typed back on the phone
+
+When a sign-in needs a code another service sent the person (a text message, WhatsApp, e-mail), ask them to type it on the phone instead. The phone encrypts it to a one-time key you made for this request: Touchque only ever holds the ciphertext. Such a request lives 5 minutes.
+
+```ruby
+key = Touchque::CodeReply.new_key   # keep key["privateKey"] for this request
+sent = tq.login.request(user, reply: { kind: "code", key: key["publicKey"], channel: "sms", target: "+**********26" })
+status = tq.login.status(sent["requestId"])   # once CONFIRMED
+code = status["reply"] && Touchque::CodeReply.open(key["privateKey"], sent["requestId"], status["reply"]["ct"])
+```
+
+## Safe Guard (Safe transactions approved on the phone)
+
+TouchqueSafeGuard is a transaction guard for a Safe: a transaction runs only with approvals signed by the P-256 keys on its approvers' phones. You send the raw transaction; the phone decodes it itself, shows its own rows and signs what it computed with a key only its biometrics unlock. Delegatecalls, changes to the Safe and proxy upgrades are governance: scheduled, time-locked and vetoable. A phone without that key yet gets `409 crypto_key_missing`.
+
+```ruby
+target = { "chainId" => 1, "safe" => safe, "guard" => guard,
+           "tx" => { "to" => to, "value" => 0, "data" => data, "operation" => 0, "nonce" => 42 } }
+sent = tq.safe_guard.request("treasurer@acme.com", "safe_payment", target.merge( # an action type from your dashboard
+  "config" => { "threshold" => 2, "govThreshold" => 3, "govDelay" => 172_800, "exitDelay" => 259_200 },
+  "batchTargets" => [multi_send_call_only],
+  "approverIndex" => 0 # this approver's index in the guard
+))
+done = tq.safe_guard.wait_for_approval(sent["requestId"]) # 5 minutes at most
+approval = done["safeTx"]["approval"]
+
+# Check it yourself: your own transaction, the approver's key from the guard on chain, and what
+# you are about to do with it: "approve" runs this transaction, "schedule" starts a governance change.
+purpose = done["safeTx"]["purpose"] == "schedule" ? "schedule" : "approve"
+check = Touchque::SafeApproval.verify(target, approval, approver_key, purpose: purpose, approver_index: 0)
+raise "approval refused: #{check["reason"]}" unless check["valid"]
+
+if purpose == "approve"
+  signatures = Touchque::SafeApproval.with_approvals(owner_signatures, [approval]) # execTransaction(..., signatures)
+else
+  data = Touchque::SafeApproval.schedule_call(safe, check["governanceHash"], [approval]) # a call to the guard; runs after govDelay
+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.
+
+## Errors, case codes and retries
+
+| Error | When |
+| --- | --- |
+| `Touchque::APIError` | Touchque answered with an error: `status`, `code` (`device_not_linked`, `already_used`...), `case_code`, `retry_after`, `data` |
+| `Touchque::NetworkError` | the request never reached Touchque (safe to retry) |
+| `Touchque::RejectedError`, `TimeoutError`, `PasskeyRequiredError` | `verify` outcomes |
+| `Touchque::WebhookSignatureError`, `WebhookReplayError` | webhooks |
+| `Touchque::ApprovalError`, `ApprovalMismatchError` | agent approvals |
+| `Touchque::ConfigError` | a missing key, an unknown action type, a wrong argument |
+
+A feature your organization cannot use here raises a `Touchque::FeatureError` (still an `APIError`, status 403) with `feature` (`device_risk`, `ai_agents`…) and `feature_reason`: `FeatureNotInPlanError`, `FeatureReadOnlyError` or `FeatureOffError` — not in its plan (an owner or admin adds it in the Touchque dashboard), being turned off (reads work for 14 days, changes are refused) or switched off on this Touchque deployment.
+
+**"Why?" case codes.** Refusals and pushes carry a 6-character case code (`K7P-2QX`): show it
+("Tell your support team: K7P-2QX"); your team opens the whole decision by it in the dashboard.
+
+**Retries.** Every request is signed with a one-time nonce, so the SDK never replays one. Retry
+`Touchque::NetworkError` at the call site; on 429 / 423 wait `retry_after` seconds. The client
+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.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test   # needs Node.js: the tests run against testing/fake-touchque-api.mjs and fixtures/
+gem build touchque.gemspec
+```
+
+## License
+
+MIT