touchque-authenticator 5.0.0__tar.gz → 5.1.0__tar.gz

{touchque_authenticator-5.0.0 → touchque_authenticator-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: touchque-authenticator
-Version: 5.0.0
+Version: 5.1.0
 Summary: Official Python SDK for Touchque Authenticator (2FA/MFA, passkeys, adaptive auth)
 Home-page: https://touchque.com
 Author: Touchque
@@ -119,6 +119,100 @@ header `X-Touchque-Token: <token>` — see
 this loop for you in the browser. Once approved, the retried request reaches
 your view exactly once.
 
+While the first-time QR is up, polls answer `{"touchque": {"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.
+
+### Refusals in your own error shape
+
+A refusal answers 401 (nobody signed in), 403 (`rejected`, `blocked`), 408 (`expired`), 423 (`frozen`) or
+429 (`rate_limited`, both with `Retry-After`), and 500 `misconfigured` / 503 `unavailable` when Touchque is
+not set up or cannot be reached. The body is `{"touchque": {"state": ..., "reason": ...}}`, with
+`"error": {"code", "message"}` on 401, 500 and 503. `error_body` sends your app's own shape instead:
+
+```python
+@app.post('/transfer')
+@require_touchque('SEND_MONEY', error_body=lambda r: {'message': r['message'], 'code': r['code']})
+def transfer():
+    ...
+# 403 {"message": "The approval was rejected.", "code": "rejected", "touchque": {"state": "rejected", ...}}
+```
+
+It is called for every answer with status 400 or above, never for a 202 step, with a dict:
+`status`; `code` (the guard's `error.code`, else the step's `reason`, else its `state`); `message`
+(`error.message`, else "The approval was rejected.", "The approval expired. Try again.", "Too many
+rejected approvals. Try again later.", "Too many attempts. Try again later." or "The approval was
+refused."); and `touchque`, a copy of the step. What it returns counts by its JSON encoding, the
+framework's own (Flask's JSON provider, `DjangoJSONEncoder`, FastAPI's `jsonable_encoder`): what encodes
+to an object (a dict, a dataclass, a pydantic model) is sent with `touchque` set to the step, so
+`@touchque/web` still sees the state (no `token` is added); anything else (a string, a list, `None`) is
+sent as it is. The status and headers stay. If it raises, or returns what cannot be encoded, the default
+body is sent and `[Touchque] error_body failed: ...` is logged. Django's `require_touchque` and FastAPI's
+`RequireTouchque` take the same option (on FastAPI it may be async); on FastAPI,
+`install_touchque_exception_handler(app)` sends it as the whole body (without it, FastAPI puts it under
+`"detail"`).
+
+Every refusal (status 400 and above) also carries `X-Touchque-State: <state>`, and
+`X-Touchque-Reason: <reason>` when the step has one: `@touchque/web` 2.1.0 reads the step from them when
+the body has no `touchque`. A page on another origin needs them in `Access-Control-Expose-Headers`.
+
+### Without API keys
+
+The adapters build the default client from `TQ_API_KEY` / `TQ_API_SECRET` on the first request, not at
+import, and never raise for it. While the keys are not set, a guarded route answers **500**
+`{"touchque": {"state": "blocked", "reason": "misconfigured"}, "error": {"code": "misconfigured",
+"message": "Two-factor approval is not configured correctly."}}` with `Cache-Control: no-store` (401
+`unauthenticated` when nobody is signed in), your view never runs, and
+`[Touchque] TQ_API_KEY and TQ_API_SECRET are not set: routes guarded by Touchque answer 500 misconfigured.`
+is logged once (see [Logging](#logging)). It is a 500, not a 503: a deploy mistake should show in your
+monitoring, not invite retries. `@touchque/web` shows "Approvals are not set up correctly on this site."
+
+## Guard inside your handler
+
+When your own checks come first (the balance, who owns the account), call `run_guard` in the handler
+instead of the decorator. It is the same guard and never raises for Touchque: send its `status` and
+`body` as JSON with the headers `guard_response_headers(result)` gives (`Cache-Control: no-store`,
+`Retry-After` on 423 and 429, `X-Touchque-State` on a refusal), and do the action once it returns
+`approved`:
+
+```python
+from flask import g, jsonify, request
+from touchque import guard_input_from_headers, guard_response_headers, run_guard
+
+@app.post('/transfer')
+def transfer():
+    amount = int(request.json['amount'])
+    if amount > balance_of(g.user):             # your checks first: no push for a transfer you refuse anyway
+        return jsonify(error='insufficient_funds'), 400
+
+    result = run_guard(
+        None, g.user.email, 'SEND_MONEY',       # None: the default client (TQ_API_KEY / TQ_API_SECRET)
+        details={'Amount': f'{amount} EUR'},    # the same on every poll: build it from your own state
+        ip=request.remote_addr, user_agent=request.headers.get('User-Agent'),
+        **guard_input_from_headers(request.headers.get),  # X-Touchque-Token, -Offline, -Code, -Code-Type
+    )
+    if 'approved' not in result:
+        return jsonify(result['body']), result['status'], guard_response_headers(result)
+
+    send_money(g.user, amount)                  # once: the approval is used up
+    return jsonify(ok=True, approval=result['approved'])
+```
+
+The answers are the decorator's. 202 `{"touchque": step, "token": ...}` until the phone answers: the
+page shows the step and sends the request again with `X-Touchque-Token` (`@touchque/web` does), and
+`approved` comes exactly once, for this user, action and details. While the first-time QR is up the 202
+step is `{"state": "enroll", "expiresAt": ...}` without `enroll`: keep the QR on screen; a new one comes
+in `enroll.qrCodeDataUrl` after the old one expired. A refusal is 401, 403, 408, 423 or 429; 500
+`misconfigured` and 503 `unavailable` when Touchque is not set up or cannot be reached.
+
+With a rate limit of your own in front of it, count a request that only polls apart from a new attempt:
+`from touchque import is_status_poll` and call it with the same arguments as `run_guard` (`None` for
+the default client too); it is true when the request only reads the status or keeps the first-time QR.
+Then pass `before_start=` to `run_guard`: it calls it at most once, right before a first-time-QR token
+would start something after all (a push now that the phone is linked, or a new QR). Charge your per-user
+limit there and return your 429 as a result (`{'status': 429, 'body': ...}`) to answer it instead, or
+`None` to go on. The relay does this for `POST /login`.
+
 ## Action types
 
 `"SEND_MONEY"` above is an action type: one kind of approval, with the title the phone shows and
@@ -609,6 +703,54 @@ else:
 
 `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.
 
+## Testing your routes
+
+`touchque.testing.FakeTouchque` 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:
+
+```python
+# test_transfer.py
+import pytest
+from touchque.testing import FakeTouchque
+
+from myapp import app  # @require_touchque('SEND_MONEY', ...) with no client
+
+
+@pytest.fixture
+def tq():
+    with FakeTouchque() as fake:  # the default client until the test ends
+        yield fake
+
+
+def test_transfer_needs_an_approval(tq):
+    client = app.test_client()
+    first = client.post('/transfer', json={'amount': 5})
+    assert first.status_code == 202
+    token = first.get_json()['token']
+
+    tq.approve()  # the person approves on the phone
+    done = client.post('/transfer', json={'amount': 5}, headers={'X-Touchque-Token': token})
+    assert done.status_code == 200
+    assert tq.requests[-1]['details'] == [{'label': 'Amount', 'value': '5 EUR'}]
+```
+
+A route given `client=` uses that client: pass the fake there instead (`tq.install()` / `tq.uninstall()`
+are the context manager's two halves).
+
+- `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(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 route.
+- Every user has a phone linked. `tq.unlink(user)` shows them the first-time QR instead
+  (`FakeTouchque(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(number_match=True)`: pushes ask for the number `47`.
+- `tq.requests` (`id`, `user`, `type`, `details`, `referenceId`, `status`) and `tq.calls` (`method`,
+  `path`, `body`): what your app asked Touchque, in order.
+- Offline approval: the code is `ABCD123`, the time-based code `123456`. Calls outside the step-up
+  (recovery, agents …) raise `TouchqueAPIException` 404. `FakeClient` is another name for it.
+
 ## Errors
 
 All SDK errors extend `TouchqueException`: `TouchqueAPIException`,
@@ -635,7 +777,7 @@ See [SECURITY.md](https://github.com/Touchque/touchque-python/blob/main/SECURITY
 
 ## 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.
+The SDK's own problems (a misconfigured guard, missing `TQ_API_KEY` / `TQ_API_SECRET` (once per process), a failed `on_challenge` or `error_body`, 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
 

{touchque_authenticator-5.0.0 → touchque_authenticator-5.1.0}/README.md

@@ -73,6 +73,100 @@ header `X-Touchque-Token: <token>` — see
 this loop for you in the browser. Once approved, the retried request reaches
 your view exactly once.
 
+While the first-time QR is up, polls answer `{"touchque": {"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.
+
+### Refusals in your own error shape
+
+A refusal answers 401 (nobody signed in), 403 (`rejected`, `blocked`), 408 (`expired`), 423 (`frozen`) or
+429 (`rate_limited`, both with `Retry-After`), and 500 `misconfigured` / 503 `unavailable` when Touchque is
+not set up or cannot be reached. The body is `{"touchque": {"state": ..., "reason": ...}}`, with
+`"error": {"code", "message"}` on 401, 500 and 503. `error_body` sends your app's own shape instead:
+
+```python
+@app.post('/transfer')
+@require_touchque('SEND_MONEY', error_body=lambda r: {'message': r['message'], 'code': r['code']})
+def transfer():
+    ...
+# 403 {"message": "The approval was rejected.", "code": "rejected", "touchque": {"state": "rejected", ...}}
+```
+
+It is called for every answer with status 400 or above, never for a 202 step, with a dict:
+`status`; `code` (the guard's `error.code`, else the step's `reason`, else its `state`); `message`
+(`error.message`, else "The approval was rejected.", "The approval expired. Try again.", "Too many
+rejected approvals. Try again later.", "Too many attempts. Try again later." or "The approval was
+refused."); and `touchque`, a copy of the step. What it returns counts by its JSON encoding, the
+framework's own (Flask's JSON provider, `DjangoJSONEncoder`, FastAPI's `jsonable_encoder`): what encodes
+to an object (a dict, a dataclass, a pydantic model) is sent with `touchque` set to the step, so
+`@touchque/web` still sees the state (no `token` is added); anything else (a string, a list, `None`) is
+sent as it is. The status and headers stay. If it raises, or returns what cannot be encoded, the default
+body is sent and `[Touchque] error_body failed: ...` is logged. Django's `require_touchque` and FastAPI's
+`RequireTouchque` take the same option (on FastAPI it may be async); on FastAPI,
+`install_touchque_exception_handler(app)` sends it as the whole body (without it, FastAPI puts it under
+`"detail"`).
+
+Every refusal (status 400 and above) also carries `X-Touchque-State: <state>`, and
+`X-Touchque-Reason: <reason>` when the step has one: `@touchque/web` 2.1.0 reads the step from them when
+the body has no `touchque`. A page on another origin needs them in `Access-Control-Expose-Headers`.
+
+### Without API keys
+
+The adapters build the default client from `TQ_API_KEY` / `TQ_API_SECRET` on the first request, not at
+import, and never raise for it. While the keys are not set, a guarded route answers **500**
+`{"touchque": {"state": "blocked", "reason": "misconfigured"}, "error": {"code": "misconfigured",
+"message": "Two-factor approval is not configured correctly."}}` with `Cache-Control: no-store` (401
+`unauthenticated` when nobody is signed in), your view never runs, and
+`[Touchque] TQ_API_KEY and TQ_API_SECRET are not set: routes guarded by Touchque answer 500 misconfigured.`
+is logged once (see [Logging](#logging)). It is a 500, not a 503: a deploy mistake should show in your
+monitoring, not invite retries. `@touchque/web` shows "Approvals are not set up correctly on this site."
+
+## Guard inside your handler
+
+When your own checks come first (the balance, who owns the account), call `run_guard` in the handler
+instead of the decorator. It is the same guard and never raises for Touchque: send its `status` and
+`body` as JSON with the headers `guard_response_headers(result)` gives (`Cache-Control: no-store`,
+`Retry-After` on 423 and 429, `X-Touchque-State` on a refusal), and do the action once it returns
+`approved`:
+
+```python
+from flask import g, jsonify, request
+from touchque import guard_input_from_headers, guard_response_headers, run_guard
+
+@app.post('/transfer')
+def transfer():
+    amount = int(request.json['amount'])
+    if amount > balance_of(g.user):             # your checks first: no push for a transfer you refuse anyway
+        return jsonify(error='insufficient_funds'), 400
+
+    result = run_guard(
+        None, g.user.email, 'SEND_MONEY',       # None: the default client (TQ_API_KEY / TQ_API_SECRET)
+        details={'Amount': f'{amount} EUR'},    # the same on every poll: build it from your own state
+        ip=request.remote_addr, user_agent=request.headers.get('User-Agent'),
+        **guard_input_from_headers(request.headers.get),  # X-Touchque-Token, -Offline, -Code, -Code-Type
+    )
+    if 'approved' not in result:
+        return jsonify(result['body']), result['status'], guard_response_headers(result)
+
+    send_money(g.user, amount)                  # once: the approval is used up
+    return jsonify(ok=True, approval=result['approved'])
+```
+
+The answers are the decorator's. 202 `{"touchque": step, "token": ...}` until the phone answers: the
+page shows the step and sends the request again with `X-Touchque-Token` (`@touchque/web` does), and
+`approved` comes exactly once, for this user, action and details. While the first-time QR is up the 202
+step is `{"state": "enroll", "expiresAt": ...}` without `enroll`: keep the QR on screen; a new one comes
+in `enroll.qrCodeDataUrl` after the old one expired. A refusal is 401, 403, 408, 423 or 429; 500
+`misconfigured` and 503 `unavailable` when Touchque is not set up or cannot be reached.
+
+With a rate limit of your own in front of it, count a request that only polls apart from a new attempt:
+`from touchque import is_status_poll` and call it with the same arguments as `run_guard` (`None` for
+the default client too); it is true when the request only reads the status or keeps the first-time QR.
+Then pass `before_start=` to `run_guard`: it calls it at most once, right before a first-time-QR token
+would start something after all (a push now that the phone is linked, or a new QR). Charge your per-user
+limit there and return your 429 as a result (`{'status': 429, 'body': ...}`) to answer it instead, or
+`None` to go on. The relay does this for `POST /login`.
+
 ## Action types
 
 `"SEND_MONEY"` above is an action type: one kind of approval, with the title the phone shows and
@@ -563,6 +657,54 @@ else:
 
 `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.
 
+## Testing your routes
+
+`touchque.testing.FakeTouchque` 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:
+
+```python
+# test_transfer.py
+import pytest
+from touchque.testing import FakeTouchque
+
+from myapp import app  # @require_touchque('SEND_MONEY', ...) with no client
+
+
+@pytest.fixture
+def tq():
+    with FakeTouchque() as fake:  # the default client until the test ends
+        yield fake
+
+
+def test_transfer_needs_an_approval(tq):
+    client = app.test_client()
+    first = client.post('/transfer', json={'amount': 5})
+    assert first.status_code == 202
+    token = first.get_json()['token']
+
+    tq.approve()  # the person approves on the phone
+    done = client.post('/transfer', json={'amount': 5}, headers={'X-Touchque-Token': token})
+    assert done.status_code == 200
+    assert tq.requests[-1]['details'] == [{'label': 'Amount', 'value': '5 EUR'}]
+```
+
+A route given `client=` uses that client: pass the fake there instead (`tq.install()` / `tq.uninstall()`
+are the context manager's two halves).
+
+- `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(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 route.
+- Every user has a phone linked. `tq.unlink(user)` shows them the first-time QR instead
+  (`FakeTouchque(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(number_match=True)`: pushes ask for the number `47`.
+- `tq.requests` (`id`, `user`, `type`, `details`, `referenceId`, `status`) and `tq.calls` (`method`,
+  `path`, `body`): what your app asked Touchque, in order.
+- Offline approval: the code is `ABCD123`, the time-based code `123456`. Calls outside the step-up
+  (recovery, agents …) raise `TouchqueAPIException` 404. `FakeClient` is another name for it.
+
 ## Errors
 
 All SDK errors extend `TouchqueException`: `TouchqueAPIException`,
@@ -589,7 +731,7 @@ See [SECURITY.md](https://github.com/Touchque/touchque-python/blob/main/SECURITY
 
 ## 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.
+The SDK's own problems (a misconfigured guard, missing `TQ_API_KEY` / `TQ_API_SECRET` (once per process), a failed `on_challenge` or `error_body`, 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
 

{touchque_authenticator-5.0.0 → touchque_authenticator-5.1.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="touchque-authenticator",
-    version="5.0.0",
+    version="5.1.0",
     description="Official Python SDK for Touchque Authenticator (2FA/MFA, passkeys, adaptive auth)",
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",

{touchque_authenticator-5.0.0 → touchque_authenticator-5.1.0}/tests/test_contract.py

@@ -1,11 +1,14 @@
 """Contract tests against the shared fake Touchque API — a real HTTP round
 trip, so request signing is verified too (not just mocked). Same scenarios
 as the Node SDK's step-up tests."""
+import time
+
 import pytest
 
 from touchque import Config, Touchque
 from touchque.exceptions import TouchqueConfigException
 from touchque.guard import is_status_poll, run_guard
+from touchque.steps import _iso_ms, verify_guard_token
 from .fake_api import fake_api  # noqa: F401 (fixture)
 
 
@@ -250,3 +253,117 @@ def test_an_approval_taken_back_is_never_used(fake_api):
     done = run_guard(tq, 'jane@acme.com', 'LOGIN', token=first['body']['token'])
     assert done['status'] == 408
     assert done['body']['touchque'] == {'state': 'expired', 'reason': 'revoked'}
+
+
+# ── first-time QR: one QR per enrollment, not one per poll ──────────────
+
+def test_enroll_polls_keep_the_qr_until_the_phone_is_linked(fake_api):
+    api = fake_api
+    tq = client_for(api)
+    first = run_guard(tq, 'new@acme.com', 'LOGIN', details={'Device': 'Mac'})
+    qr = first['body']['touchque']['enroll']
+    assert qr['qrCodeDataUrl'] == 'data:image/png;base64,QR-new@acme.com' and qr['recoveryCodes'] == ['r1']
+    ee = _iso_ms(qr['expiresAt'])
+    assert 290000 < ee - time.time() * 1000 <= 300000  # the API's own expiresAt (5 minutes)
+    claims = verify_guard_token('test_secret', first['body']['token'])
+    assert claims['st'] == 'enroll' and claims['ee'] == ee
+
+    before = len(api.calls())
+    poll = run_guard(tq, 'new@acme.com', 'LOGIN', details={'Device': 'Mac'}, token=first['body']['token'])
+    assert poll['status'] == 202
+    assert poll['body']['touchque'] == {'state': 'enroll', 'expiresAt': qr['expiresAt'],
+                                        'details': [{'label': 'Device', 'value': 'Mac'}]}
+    assert [c['path'] for c in api.calls()[before:]] == ['/users/new%40acme.com']  # no generate or reset
+    again = verify_guard_token('test_secret', poll['body']['token'])
+    assert again['st'] == 'enroll' and again['ee'] == ee
+
+    api.link('new@acme.com')  # the phone scanned the QR
+    waiting = run_guard(tq, 'new@acme.com', 'LOGIN', details={'Device': 'Mac'}, token=poll['body']['token'])
+    assert waiting['status'] == 202 and waiting['body']['touchque']['state'] == 'waiting'
+
+
+def test_an_enroll_qr_about_to_expire_is_replaced(fake_api):
+    api = fake_api
+    api.opts(secretTtlMs=1000)
+    tq = client_for(api)
+    first = run_guard(tq, 'new@acme.com', 'LOGIN')
+    assert first['body']['touchque']['enroll']['qrCodeDataUrl'] == 'data:image/png;base64,QR-new@acme.com'
+    poll = run_guard(tq, 'new@acme.com', 'LOGIN', token=first['body']['token'])
+    assert poll['status'] == 202
+    assert poll['body']['touchque']['enroll']['qrCodeDataUrl'] == 'data:image/png;base64,QR2-new@acme.com'
+    assert '/auth/secret/reset' in api.paths()
+
+
+def test_an_enroll_token_without_an_expiry_starts_again(fake_api):
+    """No "ee" (an enroll step without a QR, or a 5.0 token): every poll starts again, as before."""
+    api = fake_api
+    tq = client_for(api)
+    old = run_guard(tq, 'new@acme.com', 'LOGIN', enroll=False)
+    assert old['body']['touchque'] == {'state': 'enroll'}
+    assert 'ee' not in verify_guard_token('test_secret', old['body']['token'])
+    assert is_status_poll(tq, 'new@acme.com', 'LOGIN', token=old['body']['token']) is False
+    again = run_guard(tq, 'new@acme.com', 'LOGIN', token=old['body']['token'])
+    assert again['body']['touchque']['enroll']['qrCodeDataUrl']
+    assert '/users/new%40acme.com' not in api.paths()
+
+
+def test_is_status_poll_counts_a_bound_enroll_token(fake_api):
+    tq = client_for(fake_api)
+    token = run_guard(tq, 'new@acme.com', 'LOGIN')['body']['token']
+    assert is_status_poll(tq, 'new@acme.com', 'LOGIN', token=token) is True
+    assert is_status_poll(tq, 'other@acme.com', 'LOGIN', token=token) is False
+    assert is_status_poll(tq, 'new@acme.com', 'SEND_MONEY', token=token) is False
+    assert is_status_poll(tq, 'new@acme.com', 'LOGIN', token=token, offline=True) is False
+
+    # The poll that renews an expiring QR (or replays an old token) still counts against the limit.
+    fake_api.opts(secretTtlMs=1000)
+    expiring = run_guard(tq, 'late@acme.com', 'LOGIN')['body']['token']
+    assert verify_guard_token('test_secret', expiring)['ee']
+    assert is_status_poll(tq, 'late@acme.com', 'LOGIN', token=expiring) is False
+
+
+def test_enroll_qr_expiry_is_the_apis_or_now_plus_ttl():
+    from touchque.steps import _enroll_qr, _iso_from_ms
+    assert _enroll_qr({'qrCodeDataUrl': 'qr', 'expiresAt': '2026-11-12T10:05:00.000Z', 'ttlMs': 1000})['enroll'][
+        'expiresAt'] == '2026-11-12T10:05:00.000Z'
+    before = int(time.time() * 1000)
+    step = _enroll_qr({'qrCodeDataUrl': 'qr', 'expiresAt': 'soon', 'ttlMs': 60000})
+    assert before + 60000 <= _iso_ms(step['enroll']['expiresAt']) <= time.time() * 1000 + 60000
+    assert 'expiresAt' not in _enroll_qr({'qrCodeDataUrl': 'qr', 'expiresAt': 'soon'})['enroll']
+    assert _iso_from_ms(_iso_ms('2026-11-12T12:05:00+02:00')) == '2026-11-12T10:05:00.000Z'
+    assert _iso_ms('2026-13-12T10:05:00Z') is None and _iso_ms(1700000000000) is None
+
+
+def test_before_start_runs_once_only_when_an_enroll_token_starts(fake_api):
+    api = fake_api
+    tq = client_for(api)
+    seen = []
+
+    def hook():
+        seen.append(api.paths()[-1])
+        return None
+
+    token = run_guard(tq, 'new@acme.com', 'LOGIN', before_start=hook)['body']['token']  # a fresh attempt
+    keep = run_guard(tq, 'new@acme.com', 'LOGIN', token=token, before_start=hook)  # keeps the QR
+    assert keep['body']['touchque']['state'] == 'enroll' and seen == []
+
+    api.link('new@acme.com')
+    before = len(api.calls())
+    refused = run_guard(tq, 'new@acme.com', 'LOGIN', token=token,
+                        before_start=lambda: {'status': 429, 'body': {'error': 'RATE_LIMITED'}})
+    assert refused == {'status': 429, 'body': {'error': 'RATE_LIMITED'}}
+    assert api.paths()[before:] == ['/users/new%40acme.com']  # nothing started
+    went = run_guard(tq, 'new@acme.com', 'LOGIN', token=token, before_start=hook)
+    assert went['body']['touchque']['state'] == 'waiting' and seen == ['/users/new%40acme.com']
+
+    api.opts(secretTtlMs=1000)  # a QR within 15 s of its expiry: the hook runs before the new QR
+    late = run_guard(tq, 'late@acme.com', 'LOGIN')['body']['token']
+    renewed = run_guard(tq, 'late@acme.com', 'LOGIN', token=late, before_start=hook)
+    assert renewed['body']['touchque']['enroll']['qrCodeDataUrl'] and len(seen) == 2
+
+    api.reset()
+    fresh = run_guard(tq, 'gone@acme.com', 'LOGIN')['body']['token']
+    api.reset()  # the QR is gone: GET /users answers 404, and the hook runs before the new QR
+    gone = run_guard(tq, 'gone@acme.com', 'LOGIN', token=fresh, before_start=hook)
+    assert gone['body']['touchque']['enroll']['qrCodeDataUrl'] and len(seen) == 3
+    assert run_guard(tq, 'gone@acme.com', 'LOGIN', before_start=hook)['status'] == 202 and len(seen) == 3

touchque_authenticator-5.1.0/tests/test_contrib_django.py

@@ -0,0 +1,140 @@
+import dataclasses
+import json
+
+import pytest
+
+django = pytest.importorskip('django')
+from django.conf import settings as _settings
+if not _settings.configured:  # test_relay_django.py may have configured it already
+    _settings.configure(DEBUG=True, ALLOWED_HOSTS=['*'], DEFAULT_CHARSET='utf-8')
+    import django as _django
+    _django.setup()
+
+from django.test import RequestFactory  # noqa: E402
+
+from touchque import Config, Touchque  # noqa: E402
+from touchque.contrib.django import require_touchque  # noqa: E402
+from touchque.testing import FakeTouchque  # noqa: E402
+from .fake_api import fake_api  # noqa: F401,E402
+from .guard_helpers import MISCONFIGURED, no_keys  # noqa: F401,E402
+
+
+def make_view(tq, action='SEND_MONEY'):
+    @require_touchque(action, client=tq, user=lambda req: req.headers.get('X-User'),
+                       details=lambda req: {'Amount': '5 EUR'})
+    def transfer(request):
+        from django.http import JsonResponse
+        return JsonResponse({'done': True, 'touchque': request.touchque})
+    return transfer
+
+
+def test_full_flow(fake_api):
+    fake_api.link('jane@acme.com')
+    fake_api.opts(numberMatch=True)
+    tq = Touchque(Config(api_key='tq_test_key', api_secret='test_secret', base_url=fake_api.base_url))
+    view = make_view(tq)
+    rf = RequestFactory()
+
+    first = view(rf.post('/transfer', data=b'{}', content_type='application/json', HTTP_X_USER='jane@acme.com'))
+    assert first.status_code == 202
+    body = json.loads(first.content)
+    assert body['touchque']['number'] == '47'
+
+    fake_api.approve()
+    done = view(rf.post('/transfer', data=b'{}', content_type='application/json',
+                         HTTP_X_USER='jane@acme.com', HTTP_X_TOUCHQUE_TOKEN=body['token']))
+    assert done.status_code == 200
+    assert json.loads(done.content)['done'] is True
+
+
+def test_silent_sign_in_runs_the_view_at_once_for_a_known_browser(fake_api):
+    from .silent_vectors import PROOF
+    from django.http import JsonResponse
+
+    fake_api.link('jane@acme.com')
+    fake_api.opts(silent=True)
+    tq = Touchque(Config(api_key='tq_test_key', api_secret='test_secret', base_url=fake_api.base_url))
+
+    @require_touchque('LOGIN', client=tq, user=lambda req: 'jane@acme.com', silent_sign_in=True)
+    def login(request):
+        return JsonResponse({'done': True, 'touchque': request.touchque})
+
+    res = login(RequestFactory().post('/login/2fa', data=b'{}', content_type='application/json',
+                                      HTTP_X_TOUCHQUE_BROWSER=PROOF))
+    assert res.status_code == 200
+    body = json.loads(res.content)
+    assert body['touchque']['confirmedVia'] == 'SILENT'
+    assert [r['code'] for r in body['touchque']['reasons']][0] == 'known_browser'
+    assert fake_api.last_check()['browserProof'] == PROOF
+
+
+def make_guarded_view(ran, **options):
+    @require_touchque('SEND_MONEY', user=lambda req: req.headers.get('X-User'), **options)
+    def transfer(request):
+        from django.http import JsonResponse
+        ran.append(True)
+        return JsonResponse({'done': True})
+    return transfer
+
+
+def post(view, **headers):
+    return view(RequestFactory().post('/transfer', data=b'{}', content_type='application/json', **headers))
+
+
+def test_without_keys_the_view_answers_500_misconfigured_and_never_runs(no_keys):
+    ran = []
+    view = make_guarded_view(ran)  # no client: nothing raised at import
+    res = post(view, HTTP_X_USER='jane@acme.com')
+    assert res.status_code == 500
+    assert json.loads(res.content) == MISCONFIGURED
+    assert res['Cache-Control'] == 'no-store'
+    anonymous = post(view)
+    assert anonymous.status_code == 401 and json.loads(anonymous.content)['error']['code'] == 'unauthenticated'
+    assert ran == []
+
+
+def test_error_body_object_is_merged_and_anything_else_sent_as_it_is():
+    tq, seen = FakeTouchque(), []
+
+    def body(refusal):
+        seen.append(refusal['status'])
+        return {'message': refusal['message'], 'code': refusal['code']}
+
+    view = make_guarded_view([], client=tq, error_body=body)
+    first = post(view, HTTP_X_USER='jane@acme.com')
+    assert first.status_code == 202 and seen == []
+    tq.expire()
+    res = post(view, HTTP_X_USER='jane@acme.com', HTTP_X_TOUCHQUE_TOKEN=json.loads(first.content)['token'])
+    assert res.status_code == 408 and res['Cache-Control'] == 'no-store'
+    assert json.loads(res.content) == {'message': 'The approval expired. Try again.', 'code': 'expired',
+                                       'touchque': {'state': 'expired', 'requestId': tq.requests[-1]['id']}}
+    assert seen == [408]
+
+    listed = post(make_guarded_view([], client=tq, error_body=lambda r: [r['code']]))
+    assert listed.status_code == 401 and json.loads(listed.content) == ['unauthenticated']
+
+
+@dataclasses.dataclass
+class Problem:
+    code: str
+    message: str
+
+
+def test_refusal_headers_and_error_body_by_its_json_encoding():
+    step = {'state': 'blocked', 'reason': 'unauthenticated'}
+    res = post(make_guarded_view([], client=FakeTouchque(), error_body=lambda r: Problem(r['code'], r['message'])))
+    assert res.status_code == 401
+    assert json.loads(res.content) == {'code': 'unauthenticated', 'message': 'Sign in first.', 'touchque': step}
+    assert res['X-Touchque-State'] == 'blocked' and res['X-Touchque-Reason'] == 'unauthenticated'
+
+    broken = post(make_guarded_view([], client=FakeTouchque(), error_body=lambda r: {r['code']}))
+    assert broken.status_code == 401 and json.loads(broken.content) == {
+        'touchque': step, 'error': {'code': 'unauthenticated', 'message': 'Sign in first.'}}
+
+    tq = FakeTouchque()
+    view = make_guarded_view([], client=tq)
+    first = post(view, HTTP_X_USER='jane@acme.com')
+    assert first.status_code == 202 and not first.has_header('X-Touchque-State')
+    tq.reject()
+    res = post(view, HTTP_X_USER='jane@acme.com', HTTP_X_TOUCHQUE_TOKEN=json.loads(first.content)['token'])
+    assert res.status_code == 403 and res['X-Touchque-State'] == 'rejected' and not res.has_header('X-Touchque-Reason')