touchque-authenticator 5.0.0__tar.gz

touchque_authenticator-5.0.0/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.

touchque_authenticator-5.0.0/PKG-INFO

@@ -0,0 +1,646 @@
+Metadata-Version: 2.4
+Name: touchque-authenticator
+Version: 5.0.0
+Summary: Official Python SDK for Touchque Authenticator (2FA/MFA, passkeys, adaptive auth)
+Home-page: https://touchque.com
+Author: Touchque
+Author-email: developer@touchque.com
+Project-URL: Source, https://github.com/Touchque/touchque-python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: cryptography>=3.1; extra == "dev"
+Requires-Dist: httpx>=0.23; extra == "dev"
+Provides-Extra: proof
+Requires-Dist: cryptography>=3.1; extra == "proof"
+Provides-Extra: agent
+Requires-Dist: cryptography>=3.1; extra == "agent"
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: anyio>=3.0; extra == "fastapi"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# touchque-authenticator
+
+The official Python server SDK for [Touchque](https://touchque.com) — biometric push
+2FA, passkeys, and offline approval codes, added to any backend with one
+decorator per route. Adapters for Flask, Django and FastAPI included.
+
+[![PyPI version](https://img.shields.io/pypi/v/touchque-authenticator.svg)](https://pypi.org/project/touchque-authenticator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+📘 Full docs: **[support.touchque.com](https://support.touchque.com)**
+
+## Install
+
+```bash
+pip install touchque-authenticator
+# with a framework adapter:
+pip install "touchque-authenticator[flask]"    # or [django] / [fastapi]
+```
+
+The importable package is `touchque` (`import touchque`).
+
+## 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
+```
+
+`Touchque()` with no arguments reads these automatically.
+
+## Quick start (Flask)
+
+```python
+from flask import request, jsonify
+from touchque.contrib.flask import require_touchque
+
+@app.post('/transfer')
+@require_touchque('SEND_MONEY', details=lambda: {'Amount': f'{request.json["amount"]} EUR'})
+def transfer():
+    return jsonify(ok=True)
+```
+
+Django and FastAPI look the same:
+
+```python
+# Django
+from touchque.contrib.django import require_touchque
+
+@require_touchque('SEND_MONEY')
+def transfer(request):
+    ...
+```
+
+```python
+# FastAPI
+from touchque.contrib.fastapi import RequireTouchque, install_touchque_exception_handler
+
+install_touchque_exception_handler(app)  # optional: flattens the response shape
+
+@app.post('/transfer')
+def transfer(approval = Depends(RequireTouchque('SEND_MONEY'))):
+    ...
+```
+
+Until the user approves on their phone, the decorator answers
+**`202 {"touchque": step, "token": "..."}`** instead of running your view.
+Your frontend renders `step` in its own UI (a 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>` — see
+[`@touchque/web`](https://www.npmjs.com/package/@touchque/web), which does
+this loop for you in the browser. Once approved, the retried request reaches
+your view exactly once.
+
+## 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:
+
+```python
+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
+(`TouchqueConfigException`, "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.
+
+## Relay routes (sign-in, enrollment, passkeys, offline)
+
+Instead of hand-writing the routes a frontend such as `@touchque/web` calls,
+mount the relay: `POST /login` (two-phase, same `202` + token contract as
+above), `/enroll/start`, `/enroll/status`, `/offline/challenge|verify|totp`,
+`/passkey/authenticate/*`, `/passkey/login/*`, `/passkey/register/*`,
+`GET /passkey/credentials` and `DELETE /passkey/credentials/<id>`.
+`POST /passkey/authenticate/options` with no `email` answers options for any
+passkey of your site, for `@touchque/web`'s passkey autofill
+(`webauthn.primary_options()` with no username does the same).
+
+```python
+# Flask
+from touchque.contrib.flask import touchque_relay_blueprint
+
+def opened(request, response, info):          # open YOUR session here
+    session['user'] = info['externalUsername']  # info: externalUsername, requestId, via
+
+app.register_blueprint(touchque_relay_blueprint(
+    tq,
+    get_user_id=lambda req: session.get('user'),
+    # The user who already passed your password step. Binds POST /login and the
+    # offline routes to them; the offline routes stay off (403) without it.
+    get_login_user=lambda req: session.get('password_ok'),
+    on_authenticated=opened,
+), url_prefix='/touchque')
+```
+
+```python
+# FastAPI (callbacks may be async)
+from touchque.contrib.fastapi import touchque_relay_router
+app.include_router(touchque_relay_router(tq, get_user_id=..., get_login_user=...), prefix='/touchque')
+
+# Django (urls.py) - CSRF stays on: send X-CSRFToken from the page, or pass csrf_exempt=True
+from touchque.contrib.django import touchque_relay_urls
+urlpatterns = [path('touchque/', include(touchque_relay_urls(get_user_id=..., get_login_user=...)))]
+```
+
+Every callback gets the framework's request; `on_authenticated(request,
+response, info)` also gets the response that will be sent, so it can call
+`response.set_cookie(...)`. Other options: `rate_limit` (on by default: 20 per
+IP and 5 per username per route per minute; a dict with `window_ms` /
+`per_ip` / `per_user`, or `False`), `action_type` (default `'LOGIN'`),
+`get_details`, `allow_offline_without_first_factor` and `silent_sign_in` (see
+[Silent sign-ins](#silent-sign-ins-stop-asking-when-nothing-is-new)). Without a framework,
+call `touchque.RelayHandler(...).handle(method, path, body=..., ...)` and
+send the `RelayResponse` it returns.
+
+## The three primitives, if you're not using a framework adapter
+
+```python
+from touchque import Touchque
+
+tq = Touchque()  # from TQ_API_KEY / TQ_API_SECRET
+
+step = tq.start('SEND_MONEY', user='jane@acme.com', details={'Amount': '250 EUR', 'To': 'DE89...'})
+# step['state']: 'waiting' (show step['number']) | 'enroll' (show step['enroll']['qrCodeDataUrl'])
+#                | 'approved' | 'rejected' | 'expired' | 'passkey_required' | 'frozen' | 'blocked'
+
+latest = tq.check(step['requestId'])
+
+# Once approved, consume it exactly once, right before doing the protected thing:
+approval = tq.complete(step['requestId'], user='jane@acme.com', action='SEND_MONEY',
+                        details={'Amount': '250 EUR', 'To': 'DE89...'})
+```
+
+`complete()` verifies the approval was actually issued for this user, action
+and transaction, and can only be consumed once.
+
+## Passkeys (phishing-resistant)
+
+Push approval and offline codes stop password reuse and push fatigue, but a
+real-time phishing proxy can still relay them. A passkey can't be phished —
+the browser signs your site's real origin, and Touchque refuses any other
+(NIST SP 800-63B-4 §3.2.5). Register one via `tq.webauthn` on the server and
+`@touchque/web`'s `passkeys.register()` in the browser; optionally require it
+for critical actions in the Dashboard's Security Policy.
+
+## Offline sign
+
+```python
+ch = tq.offline.challenge(external_username='jane@acme.com', type='WITHDRAW',
+                           details={'Amount': '1,250.00 USD', 'Recipient': 'Jane Doe'})
+# show ch['qrDataUrl'] — the phone scans it offline and shows a 7-character code
+result = tq.offline.verify(challenge_id=ch['challengeId'], code=code)
+```
+
+**A QR that follows a push.** Pass the push's request id when the offline QR is the fallback for a push
+the user already started (the guard does this for you):
+
+```python
+ch = tq.offline.challenge(user, type='LOGIN', request_id=step['requestId'])
+# ch.get('challengeCode') is the number to print under the QR when number matching applies.
+```
+
+If the user **rejects the push on the phone, the offline QR dies with it**: no new QR is issued for that
+sign-in (409 `request_rejected`), a code for a QR already on screen is refused (`reason: 'request_rejected'`)
+and so is the time-based code (`verify_totp(..., request_id=...)`). With number matching, print `challengeCode`
+under the QR: the phone shows it among two decoys and the user taps the match; a wrong tap yields a code that
+fails verification.
+
+## Webhooks
+
+```python
+from touchque import WebhookEvents, WebhookReasons
+from touchque.exceptions import TouchqueWebhookSignatureException
+
+try:
+    # raw_body is text: in Flask request.get_data(as_text=True), in Django request.body.decode('utf-8').
+    event = tq.webhook.verify(raw_body=request.get_data(as_text=True), signature=request.headers['X-Signature'])
+except TouchqueWebhookSignatureException:
+    return '', 403  # not from Touchque
+if event.get('event') == WebhookEvents.APPROVAL_REVOKED:
+    end_sessions_built_on(event['requestId'])
+```
+
+Login results carry `status` (`SUCCESS` | `REJECTED`) and, when rejected, a `reason` (`WebhookReasons`):
+`user_rejected`, `user_reported_fraud`, `user_reported_coached` (the user said someone on the phone told
+them to approve), `risk_reversed`, `risk_step_up`, `approval_signature_invalid`, `device_integrity_failed`,
+`vishing_suspected` and `phishing_origin` (see Vishing Shield). Treat a reason you do not know as a rejection.
+Event webhooks carry `event` (`WebhookEvents`): `DEVICE_LINKED`, `DEVICE_UNLINKED`, `PASSKEY_REGISTERED`,
+`PASSKEY_DELETED`, `APPROVAL_RECONFIRMED`, `APPROVAL_REVOKED`. Ignore events you do not know.
+
+## Vishing Shield (someone on the phone guiding the user)
+
+The phone tells Touchque, signed with its hardware key, whether a call was active (or just ended), the screen
+was shared or the phone remote-controlled when the user tapped Approve. Depending on the server's mode:
+
+- **Passkey instead.** A user with a passkey finishes in the browser: the request stays open and turns into
+  `passkey_required` mid-flight. The step-up flow and the relay handle it; the blocking `login.verify` raises
+  `TouchquePasskeyRequiredError` (`reason == 'step_up'`). No offline or recovery code can finish such a request.
+- **Refused.** A critical action without a passkey is rejected (`reason: vishing_suspected`).
+- **Provisional.** Anything else is approved with `provisional` set on the approval dict from `complete`. Let the user
+  in, but treat the session as limited: Touchque refuses the user's critical actions (`blocked` / `provisional`)
+  until the phone re-confirms after the call (`APPROVAL_RECONFIRMED`). `APPROVAL_REVOKED` (`reason` `COACHED` or
+  `UNDO`) means end the session; an approval revoked before you consumed it can no longer be consumed
+  (409 `revoked`).
+
+**Mirror Alarm.** The first waiting step carries `canary.url`. `@touchque/web` loads it on the page showing the
+sign-in and sends a beacon to it, so a real-time phishing proxy in front of your site shows up as itself: the
+approval is refused (`reason: phishing_origin`) and the phone warns the user. Allow the canary host in your
+Content-Security-Policy (`img-src` and `connect-src`).
+
+## Touchque Actions (your code in the approval pipeline)
+
+Alerts, step-ups and refusals by country, local time, role or amount, passkeys
+for admins — from a template or a few lines of JavaScript, replayed against your
+real recent sign-ins before they go live. Full guide: [support.touchque.com/actions](https://support.touchque.com/actions).
+
+```python
+tq.actions.deploy('night-alert', trigger='approval.decided',
+                  template={'id': 'alert', 'params': {'channel': 'slack', 'when': {'countries': ['TR'], 'hours': {'from': 0, 'to': 6}}}})
+
+draft = 'exports.onExecute = async (event, api) => { if (event.context?.amount > 10000) api.stepUp("Over 10,000"); };'
+report = tq.actions.dry_run(trigger='login.request', code=draft)   # report['transitions'] → {'push→number_match': 3}
+tq.actions.deploy('big-transfers', trigger='login.request', code=draft)
+```
+
+Give Actions what only your server knows with `context=` (never shown on the
+phone): `@require_touchque('SEND_MONEY', context=lambda: {'amount': request.json['amount']})`.
+Loosening calls need a capability an admin approves on their phone. Action types
+moved to `tq.action_types` in 4.0.
+
+## AI agents (an identity per agent, never your API key)
+
+Register each agent with its **public** key; the private key stays where the agent runs. The agent signs in
+with its own key and gets a 10-minute token bound to that key (DPoP). `pip install "touchque-authenticator[agent]"`.
+
+```python
+from touchque import Touchque, TouchqueAgent, generate_agent_key
+
+keys = generate_agent_key()                      # or where the agent runs
+agent = client.agents.create('Invoice bot', ['PAY_INVOICE'], public_key=keys['public_jwk'],
+                             owner_email='ada@acme.com', platform='langchain')
+# store agent['id'] and keys['private_jwk'] in the agent's secrets (TQ_AGENT_ID, TQ_AGENT_KEY)
+
+me = TouchqueAgent().me()                        # in the agent
+```
+
+`client.agents.suspend(agent_id)` stops one agent at once, `client.agents.set_kill_switch(True)` every agent.
+
+```python
+ask = agent.request_approval('jane@example.com', 'PAY_INVOICE', [{
+    'type': 'payment_initiation', 'instructedAmount': {'currency': 'TRY', 'amount': '500.00'},
+    'creditorName': 'Jane Doe', 'creditorAccount': {'iban': 'TR330006100519786457841326'}}], reason='October rent')
+reply(f"Type {ask['challengeCode']} in the Touchque app to approve.")
+token = agent.wait_for_approval(ask['approvalId'])['approvalToken']
+
+# in your executor, right before paying: used once, only for what you are about to do
+approval = client.agents.redeem_approval(token, user='jane@example.com', type='PAY_INVOICE',
+    authorization_details={'type': 'payment_initiation', 'instructedAmount': {'currency': 'TRY', 'amount': '500.00'}})
+```
+
+In an agent framework, a policy says who approves which tool calls and what their
+phone shows; the tool runs only after the person approved, `current_approval()`
+holds the approval token inside it, and the function keeps its signature (LangChain
+`@tool`, LlamaIndex `FunctionTool.from_defaults`, OpenAI Agents SDK `@function_tool`):
+
+```python
+from touchque import ApprovalPolicy, with_touchque_approval, current_approval, approve_interruptions_with_touchque, touchque_can_use_tool, guard_mcp_session
+
+policy = ApprovalPolicy(agent, user='jane@example.com', type='PAY_INVOICE',
+    details=lambda a, tool: [{'type': 'payment_initiation', 'instructedAmount': {'currency': 'TRY', 'amount': a['amount']}, 'creditorAccount': {'iban': a['iban']}}],
+    on_challenge=lambda s, tool: reply(f"Type {s['challengeCode']} in the Touchque app to approve."))
+
+@tool
+@with_touchque_approval(policy)
+def pay_invoice(iban: str, amount: str) -> str:
+    return bank.pay(iban, amount, current_approval()['approvalToken'])
+
+state = approve_interruptions_with_touchque(result, {'pay_invoice': policy})       # OpenAI Agents SDK
+options = ClaudeAgentOptions(can_use_tool=touchque_can_use_tool({'pay_invoice': policy}))  # Claude Agent SDK
+session = guard_mcp_session(session, {'pay_invoice': policy})                      # an MCP ClientSession
+```
+
+Agents also stop when their review date passes and when their owner leaves the organization.
+
+### 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.
+
+```python
+from touchque import request_id_jag, redeem_id_jag, IdJagVerifier, verify_agent_card
+
+jag = 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 = 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 = IdJagVerifier(issuer='https://sso.touchque.com', audience='https://auth.files.example') \
+    .verify(form['assertion'], client_id=authenticated_client_id)
+
+verify_agent_card(card, card_url='https://agent.example/.well-known/agent-card.json')
+```
+
+## Shared Signals (security events from Touchque SSO)
+
+Touchque SSO tells your app when something happens to a member's account after sign-in, as Security Event Tokens
+(OpenID Shared Signals Framework 1.0): CAEP `session-revoked`, `credential-change`, `device-compliance-change`; RISC
+`account-disabled`, `credential-compromise`. The organization's admin adds your app as a receiver (Organization >
+Continuous access), by push to your endpoint or by poll. The verifier finds the keys through the issuer's
+`/.well-known/ssf-configuration` and checks the signature, `typ`, issuer, audience and that there is one event; `txn`
+is the case code of Touchque's decision. A SET does not expire: keep the `jti`s you handled and skip a repeat.
+`pip install "touchque-authenticator[agent]"`.
+
+```python
+from touchque import SecurityEventVerifier, SecurityEventError, poll_security_events
+
+verifier = SecurityEventVerifier(issuer='https://sso.touchque.com', audience='https://app.example.com')
+
+# Push (RFC 8935): the SET is the request body (application/secevent+jwt).
+@app.post('/ssf')
+def ssf():
+    try:
+        event = verifier.verify(request.get_data(as_text=True))
+    except SecurityEventError as e:  # e.code: invalid_request, invalid_key, invalid_issuer, invalid_audience
+        return {'err': e.code, 'description': str(e)}, 503 if e.code == 'temporarily_unavailable' else 400
+    if event.name == 'session-revoked':
+        end_sessions_of(event.subject.get('email'))
+    return '', 202
+
+# Poll (RFC 8936): acknowledge what you handled on the next call.
+out = poll_security_events(url=poll_url, token=stream_token, ack=handled_jtis, max_events=50)
+for jti, token in out['sets'].items():
+    event = verifier.verify(token)  # then act on it as above
+```
+
+## Silent sign-ins (stop asking when nothing is new)
+
+A user who approved on their phone in this browser a little while ago, from the same phone, network and country,
+with no risk signal since, does not need another push. Touchque's risk engine decides; your server only skips the
+push when it says so.
+
+1. In the browser, `@touchque/web` 2.0.0 with `createTouchqueWeb({ browserKey: true })` keeps a non-extractable
+   key for your site and sends a fresh, signed proof of it in the `X-Touchque-Browser` header.
+2. On the server, turn on `silent_sign_in`:
+
+```python
+# Flask (Django's require_touchque and FastAPI's RequireTouchque take the same option)
+@app.post('/login/2fa')
+@require_touchque('LOGIN', user=lambda: session.get('password_ok'), silent_sign_in=True)
+def login_2fa():
+    # g.touchque['assurance']['method'] is 'silent' when no push was needed.
+    return jsonify(ok=True)
+
+# Relay POST /login
+app.register_blueprint(touchque_relay_blueprint(
+    tq,
+    get_user_id=lambda req: session.get('user'),
+    get_login_user=lambda req: session.get('password_ok'),
+    silent_sign_in=True,  # or {'max_age_seconds': 8 * 3600} for your own limit
+), url_prefix='/touchque')
+```
+
+With it on, a new attempt that carries the header first calls `tq.risk.check`. Only an answer of exactly
+`prompt: false` approves it at once, with nothing sent to the phone: the approval has
+`assurance == {'phishingResistant': False, 'method': 'silent'}`, `confirmedVia == 'SILENT'`,
+`requestId == 'silent'` and `reasons` (`known_browser`, `recent_approval`, `same_phone`, `familiar_network`,
+`no_risk_signal`); the relay calls `on_authenticated` with `via: 'silent'`. Anything else, and any error in the
+check, starts the usual push with the proof attached, so its approval makes the browser known. Polling with the
+token never checks again. `run_guard(..., browser_proof=..., silent_sign_in=True)` does the same for your own
+framework (`silent_input_from_headers` reads the header).
+
+Touchque only lets a sign-in through silently when all of this holds: the browser proved its key and was approved
+on the phone (a confirmed push, not one approved during a call, or a passkey) within your `max_age_seconds` and at
+most 7 days ago, by the phone that is linked now; the country and the network were seen in the user's earlier
+approved sign-ins; the risk engine allows it with no risk signal; and the action is an everyday one. A critical
+action always asks. In `shadow` mode (`silentMode`) it always asks and the reasons say what would have happened.
+
+Without the adapters:
+
+```python
+browser_proof = request.headers.get('X-Touchque-Browser')
+risk = tq.risk.check(user, type='LOGIN', client_ip=request.remote_addr, browser_proof=browser_proof)
+if risk['prompt'] is False:
+    return open_session(user)  # risk['reasons'] say why
+step = tq.start('LOGIN', user, ip=request.remote_addr, browser_proof=browser_proof)  # the approval makes the browser known
+
+browsers = tq.risk.browsers(user)['browsers']  # for an "approved browsers" list
+tq.risk.forget_browsers(user)                  # all; or thumbprint=... for one
+```
+
+Forget a user's browsers after a password reset or a "sign out everywhere". `risk.check` reads the answer
+fail-closed (`parse_risk_check`): `prompt` is `False` only when Touchque answered the boolean `false`; malformed
+`reasons` become `[]` and a missing `assurance` is `'normal'`.
+
+## Never Locked Out (lost, dead or new phone)
+
+A user whose phone is gone moves to a new phone without a help desk. Colleagues they named beforehand vouch on their own
+phones, each typing a number the user reads them on a call; then a cooling-off (default 60 minutes) lets the old phone, any
+voucher or an admin stop it. The risk engine can refuse it or ask for more vouchers, and for 24 hours afterwards critical
+actions are refused. It is an option: offer it next to passkeys and the old phone's transfer, never as the only way. Every
+step is a hash-chained receipt (`receipts`); a voucher's step carries the signature of their phone's hardware key.
+
+```python
+# Settings page, after an approval on the user's phone:
+tq.recovery.set_vouchers(user, ['bo@acme.com', 'cy@acme.com'])
+
+# "I lost my phone", after the password:
+r = tq.recovery.start(user, client_ip=ip, display_name='Ada', fallback_vouchers=admins)
+show_qr(r['bindUri'])                      # the Touchque app on the new phone scans it
+now = tq.recovery.status(r['recoveryId'])  # each voucher's 'code' to read to them
+# now['status']: AWAITING_DEVICE -> VOUCHING -> COOLING -> COMPLETED (or VETOED / EXPIRED / FAILED)
+
+tq.recovery.veto(r['recoveryId'], by='admin@acme.com')  # an admin who does not believe it
+```
+
+## "Why?": case codes instead of guesswork
+
+Every approval decision names a short case code (`K7P-2QX`: 6 characters, no I, O, 0 or 1). A user who was asked to
+match a number, needed a passkey or was refused reads it out to your support team, and the team opens the whole
+decision by it in the Touchque dashboard (Logs → Look up a case): what went in, each check's verdict (the access rule
+that matched, the risk signals that were acted on and the ones only measured), and the single change that would have
+let it through. No screenshots, no log digging. The code opens nothing on its own: only your workspace sees its
+decisions.
+
+```python
+step = client.start('WITHDRAW', user, ip=request.remote_addr)
+# step['caseCode'] -> 'K7P-2QX'; step['reasons'] -> [{'code': 'critical_action', 'text': 'The action is marked critical'}]
+try:
+    client.login.request(user, type='LOGIN')
+except TouchqueAPIException as err:
+    if err.case_code:
+        show(f'Tell your support team: {err.case_code}')
+```
+
+`caseCode` is in the `login.request` and `risk.check` answers and every step (the guard keeps it while it waits);
+`TouchqueAPIException.case_code` carries it on refusals.
+
+## Blocking `verify()` and number matching
+
+`tq.login.verify()` sends the request and waits for the phone in one call. With number matching (your option, a
+workspace policy, a critical action or the risk engine can turn it on) the phone asks the user to pick a number,
+and the call returns only after they have. Pass `on_challenge`: it runs once, right after the request is created
+and before the wait. **Show `challengeCode` to the user now; the phone asks for it.**
+
+```python
+def show(challenge):
+    if challenge.get('challengeCode'):
+        notify_user(f"Pick {challenge['challengeCode']} on your phone", case=challenge.get('caseCode'))
+
+tq.login.verify(user, 'SEND_MONEY', on_challenge=show)
+```
+
+It gets a dict with `requestId`, `expiresAt` and, when present, `challengeCode`, `reasons` and `caseCode`. It is
+not called when only a passkey can approve (`verify()` raises `TouchquePasskeyRequiredError` first). An exception it
+raises is logged (`touchque` logger, warning) and ignored: `verify()` keeps waiting. In a web request, where the
+page hears nothing until you answer, use the relay or `tq.start()`: their first answer already carries the number.
+
+## Verifying the device proof (no need to trust Touchque)
+
+Every approval from a phone with a hardware key carries `approvalProof`: the phone's own
+signature over the request id, action, number-match code and the exact details it showed.
+`pip install "touchque-authenticator[proof]"`, then:
+
+```python
+from touchque import verify_approval_proof
+
+ok = verify_approval_proof(
+    event['approvalProof'], request_id=request_id, type='WITHDRAW', details=details,
+    challenge_code=challenge_code,
+    expected_public_key=user.touchque_device_key,  # stored from their first verified approval
+)
+```
+
+Without `expected_public_key` it returns `False` unless `allow_unpinned_key=True` (trust on first
+use — store `proof['publicKey']`, then pin it).
+
+## Reporting fraud
+
+Learned later that an approved request was fraud? Report it — it is the strongest signal
+Touchque's risk engine learns from, and it stays in your audit log:
+
+```python
+tq.login.report_fraud(request_id, reason='chargeback', note='Disputed by card holder')
+# reason: 'chargeback' | 'account_takeover' | 'social_engineering' | 'other'
+```
+
+## 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).
+
+```python
+p = client.qr_pairings.create(key_thumbprint, client_ip=ip, user_agent=ua)
+# show p['uri'] (touchque://pair-browser?...) as a QR code; poll:
+now = client.qr_pairings.get(p['pairingId'])          # waiting -> scanned -> confirmed
+if now['state'] == 'confirmed':
+    client.login.request(now['externalUsername'], qr_pairing=p['pairingId'])
+# or: client.qr_pairings.refuse(p['pairingId'], 'device_not_approved', '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.
+
+```python
+key = new_code_reply_key()   # pip install "touchque-authenticator[proof]"; keep key['private_key']
+sent = tq.login.request(user, reply={'kind': 'code', 'key': key['public_key'], 'channel': 'sms', 'target': '+**********26'})
+status = tq.login.status(sent['requestId'])   # once CONFIRMED
+code = open_code_reply(key['private_key'], sent['requestId'], status['reply']['ct']) if 'reply' in status else None
+```
+
+## 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`.
+
+```python
+from touchque import verify_safe_approval, with_safe_approvals, safe_schedule_call   # pip install "touchque-authenticator[proof]"
+
+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', {   # an action type from your dashboard
+    **target,
+    'config': {'threshold': 2, 'govThreshold': 3, 'govDelay': 172800, 'exitDelay': 259200},
+    '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 will do with it.
+purpose = done['safeTx']['purpose']   # 'approve' (execute it) or 'schedule' (a governance change)
+check = verify_safe_approval(target, approval, approver_key, purpose=purpose, approver_index=0)
+if not check['valid']:
+    raise RuntimeError(f"approval refused: {check['reason']}")
+if purpose == 'approve':
+    signatures = with_safe_approvals(owner_signatures, [approval])   # execTransaction(..., signatures)
+else:
+    data = safe_schedule_call(SAFE, check['governanceHash'], [approval])   # a call to the guard; runs after govDelay
+```
+
+`verify_safe_approval` 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. Without `purpose` it accepts only an approval to execute this exact transaction (`approve`); an approval that schedules a governance change covers neither the Safe nonce nor the gas fields, so it passes only when you name `purpose='schedule'`. 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`, `safe_governance_hash`, `safe_approval_message` and `safe_display_digest` are exported too.
+
+## Errors
+
+All SDK errors extend `TouchqueException`: `TouchqueAPIException`,
+`TouchqueNetworkException`, `TouchqueRejectedException`,
+`TouchqueTimeoutException`, `TouchqueWebhookSignatureException`,
+`TouchqueConfigException`.
+
+A feature your organization cannot use here raises a `TouchqueFeatureException` (still a `TouchqueAPIException`, status 403) with `feature` (`device_risk`, `ai_agents`…) and `feature_reason`: `TouchqueFeatureNotInPlanException`, `TouchqueFeatureReadOnlyException` or `TouchqueFeatureOffException` — 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.
+
+## Security
+
+- Every API request is signed HMAC-SHA256 (method, path+query, timestamp, nonce, body hash).
+- The `X-Touchque-Token` a frontend echoes back is itself signed and bound to
+  one user + action + transaction digest.
+- An approval is consumed exactly once, server-side.
+- Your API secret never leaves your server.
+
+See [SECURITY.md](https://github.com/Touchque/touchque-python/blob/main/SECURITY.md) to report a vulnerability.
+
+## Requirements
+
+- Python 3.7+
+- A [Touchque Dashboard](https://dashboard.touchque.com) account
+
+## Logging
+
+The SDK's own problems (a misconfigured guard, a failed `on_challenge`, a relay error) go to `logging.getLogger('touchque')`, which has a `NullHandler`: nothing is printed until your app configures logging (`logging.basicConfig()`, or a handler on `'touchque'`). Lines carry an error's class and message, never the request.
+
+## License
+
+MIT © [Touchque](https://touchque.com)
+
+## Touchque Login (hosted sign-in)
+
+Sign-up and sign-in pages for your own customers, on your brand, with OpenID Connect. See [support.touchque.com/touchque-login](https://support.touchque.com/touchque-login) for this SDK's client and a quickstart.