touchque-authenticator 4.2.0__py3-none-any.whl

touchque/resources/login.py

@@ -0,0 +1,296 @@
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Union
+
+# Label -> value, or an ordered list of {'label': ..., 'value': ...}.
+LoginDetails = Union[Dict[str, Union[str, int, float]], List[Dict[str, Any]]]
+from urllib.parse import quote
+from ..http_client import HttpClient
+from ..exceptions import TouchQueTimeoutException, TouchQueRejectedException, TouchQuePasskeyRequiredError, TouchQueConfigException
+
+logger = logging.getLogger('touchque')
+
+SECURITY_CHANGE_KINDS = ('password', 'mfa', 'device', 'email', 'phone')
+DESTINATION_KINDS = ('iban', 'account', 'wallet', 'address', 'payee')
+
+
+def _security_changes_body(changes: Dict[str, Any]) -> Dict[str, Any]:
+    """datetimes go out as ISO 8601 (a naive one is taken as UTC); strings and epoch milliseconds as given."""
+    out: Dict[str, Any] = {}
+    for kind, at in changes.items():
+        if at is None:
+            continue
+        if isinstance(at, datetime):
+            out[kind] = (at if at.tzinfo else at.replace(tzinfo=timezone.utc)).isoformat()
+        else:
+            out[kind] = at
+    return out
+
+
+class Login:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def request(self, external_username: str, type: str = 'LOGIN', reference_id: Optional[str] = None, client_ip: Optional[str] = None, user_agent: Optional[str] = None, require_biometric: bool = False, require_number_match: bool = False, details: Optional[LoginDetails] = None, browser_proof: Optional[str] = None, context: Optional[Dict[str, Any]] = None, challenge_digits: Optional[int] = None, expires_in: Optional[int] = None, client_signals: Optional[str] = None, security_changes: Optional[Dict[str, Any]] = None, destination: Optional[Dict[str, Any]] = None, locale: Optional[str] = None, qr_pairing: Optional[str] = None, device_risk: Optional[str] = None, device_risk_request_id: Optional[str] = None, reply: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Request a 2FA login/approval from the user's mobile device.
+
+        When the integration has behavioral biometrics enabled
+        (``TenantPolicy.behavioralBiometricsEnabled``), the response also
+        contains ``telemetryToken`` — pass it plus ``requestId`` to your
+        frontend to initialize the ``@touchque/web`` behavioral widget
+        (``tq.behavioral.attach(...)``). There is no widget in this server SDK.
+
+        ``details`` is transaction context shown on the approval screen, e.g.
+        ``{'Amount': '1,250.00 USD', 'Recipient': 'Jane Doe'}`` (shown in
+        order). At most 8 entries, labels <= 40 and values <= 120
+        characters; the API rejects (never truncates) anything outside those
+        limits. Build it from server-side state, never from browser input.
+
+        ``browser_proof`` (silent sign-ins): the browser's device-bound key
+        proof, exactly as the browser sent it (``X-TouchQue-Browser`` header,
+        made by ``@touchque/web``). When the user approves this request on the
+        phone (or with a passkey), TouchQue remembers the browser, so a later
+        ``risk.check`` can let the same browser in without asking. Pass it
+        through untouched; an invalid proof only means "a browser TouchQue
+        does not know".
+
+        ``context``: for your TouchQue Actions only (``event.context``): roles,
+        plan, amount… Any JSON object up to 4 KB. Never shown on the phone.
+
+        ``expires_in``: how long the push waits for the person, in seconds:
+        30 (default) to 300; longer suits a request the person has to read
+        first, such as an AI agent asking on their behalf.
+
+        ``qr_pairing``: a browser pairing by QR code (``client.qr_pairings``),
+        scanned and confirmed on the phone: only the phone that scanned it is
+        asked, once, with number matching, for the user it scanned for.
+
+        ``device_risk_request_id``: the page's identification from ``@touchque/web``
+        (``deviceRisk.identify()``), for this account only; or ``device_risk``,
+        the page's report (``deviceRisk.collect({ purpose })``), passed through untouched. Used
+        only when your workspace turned Device risk on: its signals only ever
+        ask for more, and a device your admin marked "step up always" asks at once.
+
+        ``client_signals``: the end user's page check from ``@touchque/web``
+        (``startClientSignals().encode()``), passed through untouched. A browser
+        driven by software asks with number matching, or is refused where the
+        workspace blocks it (403 ``automated_client``).
+
+        ``security_changes``: when the user's sign-in security last changed in
+        your system, ``{'password', 'mfa', 'device', 'email', 'phone'}`` each a
+        datetime, ISO 8601 string or epoch milliseconds. TouchQue adds what it
+        saw itself; access rules and Actions read the minutes since each
+        (``minutesSince.mfaChange``, ``.deviceChange``, ...), e.g. refuse
+        ``PAYOUT_CHANGE`` within 24 hours of a 2FA change.
+
+        ``destination``: where the action sends money or value,
+        ``{'kind': 'iban'|'account'|'wallet'|'address'|'payee', 'value': ..., 'known': [...]}``.
+        The phone shows it in full in groups of four, with a warning when it
+        looks like one the user used before but is not the same; the answer's
+        ``destination`` is ``{'known', 'lookalike'}``. Do not repeat it in ``details``.
+
+        ``locale``: ``'tr'`` (default) or ``'en'``, the language of those rows.
+
+        ``reply``: ask the person to type back on the phone a sign-in code another service sent
+        them, ``{'kind': 'code', 'key': new_code_reply_key()['public_key'], 'channel': 'sms',
+        'target': '+**********26'}``. The phone encrypts it to ``key``; ``status()['reply']['ct']``
+        holds only the ciphertext: open it with ``open_code_reply``. Such a request lives 5
+        minutes. Not with ``qr_pairing``.
+        """
+        payload = {
+            'externalUsername': external_username,
+            'type': type
+        }
+        if reference_id is not None:
+            payload['referenceId'] = reference_id
+        if client_ip is not None:
+            payload['clientIp'] = client_ip
+        if user_agent is not None:
+            payload['userAgent'] = user_agent
+        if require_biometric:
+            payload['requireBiometric'] = True
+        if require_number_match:
+            payload['requireNumberMatch'] = True
+        if challenge_digits in (2, 3):
+            payload['challengeDigits'] = challenge_digits
+        if expires_in is not None:
+            payload['expiresIn'] = expires_in
+        if qr_pairing:
+            payload['qrPairing'] = qr_pairing
+        if reply is not None:
+            payload['reply'] = reply
+        if client_signals:
+            payload['clientSignals'] = client_signals
+        if device_risk:
+            payload['deviceRisk'] = device_risk
+        if device_risk_request_id:
+            payload['deviceRiskRequestId'] = device_risk_request_id
+        if details:
+            payload['details'] = details
+        if browser_proof:
+            payload['browserProof'] = browser_proof
+        if context:
+            payload['context'] = context
+        if security_changes:
+            payload['securityChanges'] = _security_changes_body(security_changes)
+        if destination:
+            payload['destination'] = destination
+        if locale:
+            payload['locale'] = locale
+
+        return self._http.post('/login/request', payload)
+
+    def status(self, request_id: str) -> Dict[str, Any]:
+        """Check the current status of a login request."""
+        return self._http.get(f"/login/status/{quote(request_id, safe='')}")
+
+    def wait_for_approval(self, request_id: str, timeout_ms: int = 30000, poll_interval_ms: int = 400) -> Dict[str, Any]:
+        """Wait (poll) until the user approves or rejects a request you already sent with ``request``.
+
+        Returns ``{'approved': True, 'status': 'CONFIRMED', 'requestId', 'assurance', 'confirmedVia',
+        'provisional'}``. Raises ``TouchQueRejectedException`` when the user said no,
+        ``TouchQueTimeoutException`` when the request expired or ``timeout_ms`` ran out, and
+        ``TouchQuePasskeyRequiredError`` (``reason='step_up'``) when the user tapped Approve
+        during a call and the request now waits for a passkey in the browser::
+
+            req = tq.login.request(user, 'SEND_MONEY')
+            tq.login.wait_for_approval(req['requestId'], timeout_ms=60000)"""
+        start_time = time.time() * 1000
+
+        while True:
+            status_result = self.status(request_id)
+            status = status_result.get('status')
+
+            if status == 'CONFIRMED':
+                return {
+                    'approved': True,
+                    'status': status,
+                    'requestId': request_id,
+                    'assurance': status_result.get('assurance'),
+                    'confirmedVia': status_result.get('confirmedVia'),
+                    # Vishing Shield: approved during a call; critical actions wait for the phone to re-confirm.
+                    'provisional': bool(status_result.get('provisional')),
+                }
+
+            if status == 'REJECTED':
+                raise TouchQueRejectedException(f"Request {request_id} was rejected by the user.")
+
+            if status == 'EXPIRED':
+                raise TouchQueTimeoutException(f"Request {request_id} expired before it was approved.")
+
+            # Vishing Shield: tapped during a call, the request now waits for a passkey in the browser.
+            if status == 'PENDING' and status_result.get('requiresPasskey'):
+                raise TouchQuePasskeyRequiredError(request_id, 'step_up')
+
+            elapsed = (time.time() * 1000) - start_time
+            if elapsed > timeout_ms:
+                raise TouchQueTimeoutException(f"Waiting for approval timed out after {timeout_ms}ms")
+
+            time.sleep(poll_interval_ms / 1000)
+
+    def verify(self, external_username: str, type: str = 'LOGIN', reference_id: Optional[str] = None, client_ip: Optional[str] = None, user_agent: Optional[str] = None, require_biometric: bool = False, require_number_match: bool = False, timeout_ms: int = 30000, details: Optional[LoginDetails] = None, browser_proof: Optional[str] = None, on_challenge: Optional[Callable[[Dict[str, Any]], Any]] = None, context: Optional[Dict[str, Any]] = None, challenge_digits: Optional[int] = None, security_changes: Optional[Dict[str, Any]] = None, destination: Optional[Dict[str, Any]] = None, locale: Optional[str] = None) -> Dict[str, Any]:
+        """Request a login and wait (poll) until the user approves or rejects it.
+
+        With number matching (your ``require_number_match``, a workspace policy
+        or the risk engine can turn it on) the user must pick a number on the
+        phone. ``on_challenge`` is called once, right after the request is
+        created and before any waiting, with ``{'requestId', 'challengeCode',
+        'expiresAt', 'reasons', 'caseCode'}``: show ``challengeCode`` to the
+        user now; the phone asks for it. An exception it raises is logged and
+        ignored (verify keeps waiting). It is not called when only a passkey
+        can approve::
+
+            tq.login.verify(user, 'SEND_MONEY',
+                            on_challenge=lambda c: c.get('challengeCode') and show(f"Pick {c['challengeCode']} on your phone"))
+
+        Raises ``TouchQuePasskeyRequiredError`` when a passkey must approve it:
+        a phishing-resistant policy (``reason='policy'``, no push sent), or the
+        user tapped Approve during a call (``reason='step_up'``, Vishing Shield):
+        finish it in the browser with ``@touchque/web``."""
+        request_result = self.request(external_username, type, reference_id, client_ip, user_agent, require_biometric, require_number_match, details, browser_proof, context, challenge_digits, security_changes=security_changes, destination=destination, locale=locale)
+        request_id = request_result['requestId']
+        if request_result.get('requiresPasskey'):
+            raise TouchQuePasskeyRequiredError(request_id)
+
+        if on_challenge is not None:
+            challenge = {'requestId': request_id, 'expiresAt': request_result.get('expiresAt')}
+            for key in ('challengeCode', 'reasons', 'caseCode'):
+                if request_result.get(key):
+                    challenge[key] = request_result[key]
+            try:
+                on_challenge(challenge)
+            except Exception as err:  # noqa: BLE001 — the user's callback must not stop the wait
+                # err.__class__, not type(err): the parameter `type` shadows the builtin here.
+                logger.warning('[TouchQue] on_challenge failed: %s: %s', err.__class__.__name__, err)
+
+        start_time = time.time() * 1000
+        poll_interval_sec = 0.4
+
+        while True:
+            status_result = self.status(request_id)
+            status = status_result.get('status')
+
+            if status == 'CONFIRMED':
+                return {
+                    'approved': True,
+                    'status': status,
+                    'requestId': request_id,
+                    'challengeCode': request_result.get('challengeCode'),
+                    'assurance': status_result.get('assurance'),
+                    'confirmedVia': status_result.get('confirmedVia'),
+                    # Vishing Shield: approved during a call; critical actions wait for the phone to re-confirm.
+                    'provisional': bool(status_result.get('provisional')),
+                }
+
+            if status == 'REJECTED':
+                raise TouchQueRejectedException(f"Request {request_id} was rejected by the user.")
+
+            if status == 'EXPIRED':
+                raise TouchQueTimeoutException(f"Request {request_id} expired before it was approved.")
+
+            # Vishing Shield: tapped during a call, the request now waits for a passkey in the browser.
+            if status == 'PENDING' and status_result.get('requiresPasskey'):
+                raise TouchQuePasskeyRequiredError(request_id, 'step_up')
+
+            elapsed = (time.time() * 1000) - start_time
+            if elapsed > timeout_ms:
+                raise TouchQueTimeoutException(f"Login verification timed out after {timeout_ms}ms")
+
+            time.sleep(poll_interval_sec)
+
+    def approve_with_recovery_code(self, request_id: str, code: str) -> Dict[str, Any]:
+        """Approve a pending 2FA request using a Recovery Code (bypasses mobile device)."""
+        return self._http.post('/login/recovery', {
+            'requestId': request_id,
+            'code': code
+        })
+
+    def consume(self, request_id: str) -> Dict[str, Any]:
+        """Uses an approved request exactly once. The first call on a
+        CONFIRMED request wins atomically; every later call (a replayed
+        token, a retried form post) raises ``TouchQueAPIException`` with
+        ``code='already_used'`` (409)."""
+        return self._http.post(f"/login/{quote(request_id, safe='')}/consume", {})
+
+    FRAUD_REASONS = ('chargeback', 'account_takeover', 'social_engineering', 'other')
+
+    def report_fraud(self, request_id: str, reason: Optional[str] = None, note: Optional[str] = None) -> Dict[str, Any]:
+        """Report a request you later learned was fraud — a chargeback, a
+        confirmed account takeover, a scam the user was talked into. TouchQue's
+        risk engine learns from it (it is the strongest signal it gets) and the
+        report is kept in your audit log. The request's status does not change.
+        Safe to call more than once: a repeat answers ``alreadyReported: True``.
+
+        :param reason: one of ``Login.FRAUD_REASONS`` (default ``'other'``).
+        :param note: free text for your audit log, at most 500 characters.
+        """
+        if not request_id:
+            raise TouchQueConfigException('report_fraud() needs the request id')
+        payload: Dict[str, Any] = {}
+        if reason:
+            payload['reason'] = reason
+        if note:
+            payload['note'] = note
+        return self._http.post(f"/login/{quote(request_id, safe='')}/report-fraud", payload)

touchque/resources/mobile.py

@@ -0,0 +1,130 @@
+"""
+TouchQue Mobile SDK, your backend's side: your own iOS/Android app is the
+approver of your users (white-label); they never install the TouchQue app.
+
+1. A user signed in to your app turns approvals on: ``create_enrollment``
+   gives a one-time token; your app hands it to the SDK (``TouchQue.enroll``).
+2. Ask for approvals as always (``login.request``, ``start``, guards...):
+   they reach your app over the SDK's encrypted connection.
+3. TouchQue holds no push key of your app. For each request it sends you a
+   signed MOBILE_PUSH webhook: verify it (``webhook.verify``), then
+   ``mobile_push_from_webhook(event)`` gives the APNs payload / FCM data to
+   send with your own credentials.
+"""
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+
+def mobile_push_from_webhook(event: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """The push to send for a verified MOBILE_PUSH webhook, or None for any other event.
+
+    Returns ``deviceId``, ``externalUsername``, ``platform``, ``pushToken`` (None: send by your
+    own user -> device mapping), ``requestId``, ``expiresAt``, ``kind``, ``alert`` (English,
+    translate it), ``apns`` (the APNs payload: alert + the custom key ``touchque``) and
+    ``fcmData`` (the FCM data map). The data carries no secret, no details and no number.
+    """
+    if not isinstance(event, dict) or event.get('event') != 'MOBILE_PUSH':
+        return None
+    data = event.get('data') or {}
+    touchque = data.get('touchque') if isinstance(data.get('touchque'), str) else json.dumps(data.get('touchque') or {})
+    alert = event.get('alert') or None
+    aps: Dict[str, Any] = {'sound': 'default', 'interruption-level': 'time-sensitive'}
+    if alert:
+        aps['alert'] = alert
+    return {
+        'deviceId': event.get('deviceId'),
+        'externalUsername': event.get('externalUsername'),
+        'platform': 'android' if event.get('platform') == 'android' else 'ios',
+        'pushToken': event.get('pushToken') if isinstance(event.get('pushToken'), str) else None,
+        'requestId': event.get('requestId'),
+        'expiresAt': event.get('expiresAt'),
+        'kind': event['kind'] if event.get('kind') in ('notice', 'test') else 'approval',  # test: a test push from the dashboard
+        'alert': alert,
+        'apns': {'aps': aps, 'touchque': touchque},
+        'fcmData': {'touchque': touchque},
+    }
+
+
+def is_mobile_push_expired(push: Dict[str, Any], now: Optional[datetime] = None) -> bool:
+    """True once a push is past its request's expiry (don't send it any more)."""
+    expires = push.get('expiresAt') if isinstance(push, dict) else None
+    if not expires:
+        return False
+    at = datetime.fromisoformat(str(expires).replace('Z', '+00:00'))
+    return at <= (now or datetime.now(timezone.utc))
+
+
+class Mobile:
+    """Enrollment tokens, the devices inside your app and your Mobile SDK settings."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def create_enrollment(self, external_username: str, replace: bool = False,
+                          ttl_seconds: Optional[int] = None) -> Dict[str, Any]:
+        """A one-time enrollment token for a user you signed in. Whoever spends it becomes the
+        user's approver, so authenticate the user first. Raises TouchQueAPIException
+        ``already_enrolled`` (pass ``replace=True``) or ``account_frozen``."""
+        if not external_username:
+            raise TouchQueConfigException('mobile.create_enrollment() needs the user (external_username)')
+        body: Dict[str, Any] = {'externalUsername': external_username}
+        if replace:
+            body['replace'] = True
+        if ttl_seconds is not None:
+            body['ttlSeconds'] = ttl_seconds
+        return self._http.post('/mobile/enrollments', body)
+
+    def list_devices(self, external_username: Optional[str] = None, status: Optional[str] = None,
+                     limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        """The devices inside your app (default: active ones), newest first: ``{devices, nextCursor}``."""
+        params: Dict[str, Any] = {}
+        if external_username:
+            params['externalUsername'] = external_username
+        if status:
+            params['status'] = status
+        if limit is not None:
+            params['limit'] = limit
+        if cursor:
+            params['cursor'] = cursor
+        return self._http.get('/mobile/devices', params)
+
+    def get_device(self, device_id: str) -> Dict[str, Any]:
+        if not device_id:
+            raise TouchQueConfigException('mobile.get_device() needs the device id')
+        return self._http.get('/mobile/devices/' + quote(device_id, safe=''))['device']
+
+    def remove_device(self, device_id: str) -> Dict[str, Any]:
+        """Stops a device from approving (the user has no approver until you enrol again)."""
+        if not device_id:
+            raise TouchQueConfigException('mobile.remove_device() needs the device id')
+        return self._http.delete('/mobile/devices/' + quote(device_id, safe=''))
+
+    def test_push(self, device_id: str) -> Dict[str, Any]:
+        """A harmless push to the device, the way a request would reach it: ``via`` 'touchque' (your key for
+        its platform) or 'webhook' (MOBILE_PUSH, kind 'test'); ``ok``: APNs / FCM accepted it."""
+        if not device_id:
+            raise TouchQueConfigException('mobile.test_push() needs the device id')
+        return self._http.post('/mobile/devices/' + quote(device_id, safe='') + '/test-push', {})
+
+    def settings(self) -> Dict[str, Any]:
+        return self._http.get('/mobile/settings')['settings']
+
+    def update_settings(self, **changes: Any) -> Dict[str, Any]:
+        """Which apps may enrol, whether they must prove themselves, and your push keys: ``ios_app_ids``,
+        ``android_packages``, ``android_certs`` ({package: [SHA-256 of its signing certificate]}),
+        ``attestation`` ('off' | 'optional' | 'required'), ``enroll_ttl_seconds``,
+        ``apns`` ({keyId, teamId, topic, key: the .p8 text, production}; TouchQue then sends the iOS push
+        itself) and ``fcm`` ({serviceAccount: the JSON}; the Android push). None removes a key; the keys
+        are never shown back (``settings()['push']``)."""
+        names = {'ios_app_ids': 'iosAppIds', 'android_packages': 'androidPackages', 'android_certs': 'androidCerts',
+                 'attestation': 'attestation', 'enroll_ttl_seconds': 'enrollTtlSeconds',
+                 'apns': 'apns', 'fcm': 'fcm'}
+        unknown = set(changes) - set(names)
+        if unknown:
+            raise TouchQueConfigException('mobile.update_settings(): unknown setting ' + ', '.join(sorted(unknown)))
+        return self._http.put('/mobile/settings', {names[k]: v for k, v in changes.items()})['settings']

touchque/resources/offline.py

@@ -0,0 +1,138 @@
+import base64
+import hashlib
+import hmac
+import time
+from typing import Any, Dict, List, Optional
+
+from ..http_client import HttpClient
+from ..exceptions import TouchQueAPIException
+
+_CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+
+
+class Offline:
+    """Offline Sign — QR challenge / typed code approvals that work with the
+    phone offline (no internet on the device)."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def challenge(
+        self,
+        external_username: str,
+        type: str = 'LOGIN',
+        details: Optional[Any] = None,
+        client_ip: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+        include_qr_image: bool = True,
+        request_id: Optional[str] = None,
+        require_number_match: bool = False,
+    ) -> Dict[str, Any]:
+        """Issues an offline QR challenge. Returns
+        ``{challengeId, qr, qrDataUrl, expiresAt, expiresInSeconds, totpAvailable}``
+        (+ ``challengeCode`` when number matching applies: print it under the QR; the
+        phone offers it among two decoys and the user taps the match).
+        ``details`` is REQUIRED for critical action types.
+
+        ``request_id`` is the push this QR is a fallback for: once the phone REJECTS it the QR
+        is dead (no new QR is issued, a code for the old one is refused with ``request_rejected``),
+        and a push with number matching makes the QR show the same number. Always pass it
+        when the QR follows a push.
+        """
+        body: Dict[str, Any] = {'externalUsername': external_username, 'type': type}
+        if details is not None:
+            body['details'] = details
+        if client_ip is not None:
+            body['clientIp'] = client_ip
+        if user_agent is not None:
+            body['userAgent'] = user_agent
+        if ttl_seconds is not None:
+            body['ttlSeconds'] = ttl_seconds
+        if not include_qr_image:
+            body['includeQrImage'] = False
+        if request_id is not None:
+            body['requestId'] = request_id
+        if require_number_match:
+            body['requireNumberMatch'] = True
+        return self._http.post('/offline/challenge', body)
+
+    def verify(self, challenge_id: str, code: str) -> Dict[str, Any]:
+        """Verifies the 7-character code shown on the phone. Never raises for
+        a wrong/expired/used code — check ``approved``; ``reason`` is one of
+        ``invalid_code | locked | expired | used | unknown_challenge |
+        request_rejected | too_many_failures | device_not_enrolled``.
+        """
+        return self._not_approved_as_result(
+            lambda: self._http.post('/offline/verify', {'challengeId': challenge_id, 'code': code})
+        )
+
+    def verify_totp(self, external_username: str, code: str, type: str = 'LOGIN',
+                     client_ip: Optional[str] = None, request_id: Optional[str] = None) -> Dict[str, Any]:
+        """Verifies the rolling time-based code (no QR scan needed). Refused
+        for critical action types. ``request_id``: the push this sign-in belongs
+        to — a code is refused (``request_rejected``) once the phone rejected it."""
+        body: Dict[str, Any] = {'externalUsername': external_username, 'code': code, 'type': type}
+        if client_ip is not None:
+            body['clientIp'] = client_ip
+        if request_id is not None:
+            body['requestId'] = request_id
+        return self._not_approved_as_result(lambda: self._http.post('/offline/totp/verify', body))
+
+    def totp_verifiers(self, external_usernames: List[str], from_step: Optional[int] = None,
+                       steps: Optional[int] = None) -> Dict[str, Any]:
+        """For checking typed time-based codes while your server cannot reach
+        TouchQue (an outage): salted, slow digests of each user's next codes,
+        never a key. Up to 1,000 users and 24,000 user-steps a call; ``steps`` 1-480 (default 480, four hours)
+        from ``from_step`` (default: the current 30-second step). Returns
+        ``{stepSeconds, fromStep, steps, notAfterStep, kdf, users: [{externalUsername,
+        fromStep, salt, digests}]}`` with only the users who can use time-based codes
+        now. Check a typed code with :meth:`match_totp_verifier`. Requires the
+        workspace policies ``offlineTotpEnabled`` and ``outageVerifiersEnabled``.
+        Fetch again every few minutes: removed and frozen users fall out."""
+        body: Dict[str, Any] = {'externalUsernames': list(external_usernames)}
+        if from_step is not None:
+            body['fromStep'] = from_step
+        if steps is not None:
+            body['steps'] = steps
+        return self._http.post('/offline/totp/verifiers', body)
+
+    @staticmethod
+    def match_totp_verifier(verifiers: Dict[str, Any], user: Dict[str, Any], code: str,
+                            at: Optional[float] = None) -> Optional[int]:
+        """Checks a typed code against one user's digests from
+        :meth:`totp_verifiers` without calling TouchQue. Returns the step the
+        code belongs to (the current one or one either side), or ``None``.
+        Accept each step once: remember the step you accepted for the user and
+        refuse codes for it or an older one. ``at``: Unix time (default now)."""
+        given = ''.join(code.upper().split()).replace('-', '') if isinstance(code, str) else ''
+        if len(given) != 7 or any(c not in _CODE_ALPHABET for c in given):
+            return None
+        kdf = verifiers['kdf']
+        length = kdf['length']
+        now = int((time.time() if at is None else at) // verifiers['stepSeconds'])
+        salt = base64.b64decode(user['salt'])
+        digests = base64.b64decode(user['digests'])
+        for step in (now, now - 1, now + 1):
+            if step < user['fromStep'] or step > verifiers['notAfterStep']:
+                continue
+            i = (step - user['fromStep']) * 2 * length
+            if i + 2 * length > len(digests):
+                continue
+            got = hashlib.pbkdf2_hmac('sha256', given.encode(), salt + f':{step}'.encode(), kdf['iterations'], length)
+            if hmac.compare_digest(digests[i:i + length], got) or hmac.compare_digest(digests[i + length:i + 2 * length], got):
+                return step
+        return None
+
+    @staticmethod
+    def _not_approved_as_result(call) -> Dict[str, Any]:
+        try:
+            return call()
+        except TouchQueAPIException as err:
+            if err.status is not None and err.status < 500:
+                return {
+                    'approved': False,
+                    'reason': err.reason or err.code or (err.data or {}).get('error'),
+                    'attemptsLeft': err.attempts_left,
+                }
+            raise

touchque/resources/qr_pairings.py

@@ -0,0 +1,93 @@
+"""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.
+
+1. Your page gets the thumbprint of its browser key (``@touchque/web``
+   ``browserKey.thumbprint()``) and sends it to your server.
+2. ``create(key_thumbprint, client_ip=..., user_agent=...)`` registers a
+   pairing and returns ``uri`` (``touchque://pair-browser?...``): show it as a
+   QR code. It can be scanned once, for ``ttl_seconds`` (default 120). The
+   nonce in it never leaves your server and the QR: TouchQue keeps only its hash.
+3. Poll ``get(pairing_id)``: ``scanned`` once a phone holding one of your users'
+   accounts read it (``externalUsername``, ``proximity``), ``confirmed`` once
+   the person went on, ``reported`` when they said someone told them to scan
+   it (their 2FA freezes).
+4. ``login.request(external_username, qr_pairing=pairing_id)`` asks that phone,
+   once, with number matching; the browser key's fingerprint is one of the rows
+   the phone signs. When your own checks say no, ``refuse(pairing_id, reason,
+   message)`` and the phone shows why.
+"""
+import base64
+import hashlib
+import os as _os  # create() takes an `os` argument, which would hide the module there
+import re
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+#: What ``refuse`` may tell the phone.
+QR_PAIRING_REFUSAL_REASONS = ('policy', 'device_not_approved', 'too_many_browsers', 'rate_limited', 'no_account', 'other')
+
+_B64URL_43 = re.compile(r'^[A-Za-z0-9_-]{43}$')
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b'=').decode('ascii')
+
+
+def qr_pairing_uri(pairing_id: str, nonce: str, key_thumbprint: str) -> str:
+    """What the QR code says: ``touchque://pair-browser?v=1&p=<pairing>&n=<nonce>&k=<key thumbprint>``."""
+    q = lambda v: quote(v, safe='')  # noqa: E731
+    return f'touchque://pair-browser?v=1&p={q(pairing_id)}&n={q(nonce)}&k={q(key_thumbprint)}'
+
+
+def _path(pairing_id: str, method: str, rest: str = '') -> str:
+    if not isinstance(pairing_id, str) or not pairing_id:
+        raise TouchQueConfigException(f'qr_pairings.{method}() needs the pairing_id.')
+    return f'/qr-pairings/{quote(pairing_id, safe="")}{rest}'
+
+
+class QrPairings:
+    """Browser pairings by QR code (``POST /qr-pairings``)."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def create(self, key_thumbprint: str, client_ip: Optional[str] = None, user_agent: Optional[str] = None,
+               browser: Optional[str] = None, os_name: Optional[str] = None, ttl_seconds: Optional[int] = None,
+               os: Optional[str] = None) -> Dict[str, Any]:
+        """Registers a pairing for one browser: ``{pairingId, expiresAt, nonce, uri}``; show ``uri`` as a QR code.
+        ``os=`` is the same as ``os_name=`` (the name the other SDKs use)."""
+        if os_name is None:
+            os_name = os
+        if not isinstance(key_thumbprint, str) or not _B64URL_43.match(key_thumbprint):
+            raise TouchQueConfigException('qr_pairings.create() needs key_thumbprint: the RFC 7638 thumbprint of the browser key, base64url (43 characters).')
+        if ttl_seconds is not None and (not isinstance(ttl_seconds, int) or isinstance(ttl_seconds, bool) or not 30 <= ttl_seconds <= 300):
+            raise TouchQueConfigException('qr_pairings.create(): ttl_seconds must be 30 to 300.')
+        nonce = _b64url(_os.urandom(32))
+        body: Dict[str, Any] = {'nonceHash': _b64url(hashlib.sha256(nonce.encode('utf-8')).digest()), 'keyThumbprint': key_thumbprint}
+        for key, value in (('clientIp', client_ip), ('userAgent', user_agent), ('browser', browser), ('os', os_name), ('ttlSeconds', ttl_seconds)):
+            if value is not None and value != '':
+                body[key] = value
+        created = self._http.post('/qr-pairings', body)
+        return {**created, 'nonce': nonce, 'uri': qr_pairing_uri(created['pairingId'], nonce, key_thumbprint)}
+
+    def get(self, pairing_id: str) -> Dict[str, Any]:
+        """Where a pairing stands; once scanned, who scanned it and how near the phone was."""
+        return self._http.get(_path(pairing_id, 'get'))
+
+    def refuse(self, pairing_id: str, reason: str, message: str, case_code: Optional[str] = None,
+               device_code: Optional[str] = None) -> Dict[str, Any]:
+        """Your own checks refused a scanned pairing; the phone shows ``message``.
+        Only a ``scanned`` or ``confirmed`` pairing can be refused (409 ``not_open``)."""
+        if reason not in QR_PAIRING_REFUSAL_REASONS:
+            raise TouchQueConfigException(f'qr_pairings.refuse(): reason must be one of {", ".join(QR_PAIRING_REFUSAL_REASONS)}.')
+        if not isinstance(message, str) or not message.strip():
+            raise TouchQueConfigException('qr_pairings.refuse() needs message: what the phone shows (up to 300 characters).')
+        body: Dict[str, Any] = {'reason': reason, 'message': message}
+        if case_code:
+            body['caseCode'] = case_code
+        if device_code:
+            body['deviceCode'] = device_code
+        return self._http.post(_path(pairing_id, 'refuse', '/outcome'), body)