touchque-authenticator 4.2.0__py3-none-any.whl

touchque/resources/recovery.py

@@ -0,0 +1,118 @@
+"""
+Never Locked Out: move a user whose phone is lost, dead or replaced to a new
+phone without a help desk.
+
+1. Let users name colleagues who can vouch for them (``set_vouchers``), behind
+   an approval on their phone.
+2. When the phone is gone, after the password (or your IdP): ``start``. Show
+   ``bindUri`` as a QR for the TouchQue app on the new phone, then poll
+   ``status`` and show each voucher's ``code``: the user reads it to the
+   colleague on a call, who types it on their own phone.
+3. After the cooling-off nobody vetoed, the account is on the new phone
+   (``status == 'COMPLETED'``); critical actions wait 24 h (probation).
+
+Admins can stop a running recovery with ``veto``.
+"""
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+OPEN_STATUSES = ('AWAITING_DEVICE', 'VOUCHING', 'COOLING')
+
+
+def is_recovery_open(recovery: Dict[str, Any]) -> bool:
+    """A recovery still waiting for the new phone, the vouchers or the cooling-off."""
+    return isinstance(recovery, dict) and recovery.get('status') in OPEN_STATUSES
+
+
+class Recovery:
+    """Never Locked Out: vouchers, start, status, list and veto."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def vouchers(self, external_username: str) -> Dict[str, Any]:
+        """The colleagues a user named, and whether each can vouch today."""
+        if not external_username:
+            raise TouchQueConfigException('recovery.vouchers() needs the user (external_username)')
+        return self._http.get('/recovery/vouchers', {'externalUsername': external_username})
+
+    def set_vouchers(self, external_username: str, vouchers: List[str]) -> Dict[str, Any]:
+        """Replaces the user's vouchers (at most 5 are kept). Ask for the
+        user's phone first: whoever sets them chooses who may move the account."""
+        if not external_username:
+            raise TouchQueConfigException('recovery.set_vouchers() needs the user (external_username)')
+        if not isinstance(vouchers, list):
+            raise TouchQueConfigException('recovery.set_vouchers() needs a list of vouchers')
+        return self._http.post('/recovery/vouchers', {'externalUsername': external_username, 'vouchers': vouchers})
+
+    def start(
+        self,
+        external_username: str,
+        client_ip: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        display_name: Optional[str] = None,
+        fallback_vouchers: Optional[List[str]] = None,
+        required: Optional[int] = None,
+        cool_off_minutes: Optional[int] = None,
+        details: Optional[List[Dict[str, str]]] = None,
+        notice_details: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """Starts moving the user to a new phone. Call it only after the first
+        factor. Raises TouchQueAPIException with ``code`` ``not_enough_vouchers``,
+        ``recovery_in_progress``, ``blocked``, ``frozen`` or ``rate_limited``::
+
+            r = tq.recovery.start(user, client_ip=ip, display_name='Ada')
+            show_qr(r['bindUri'])  # the new phone scans it
+        """
+        if not external_username:
+            raise TouchQueConfigException('recovery.start() needs the user (external_username)')
+        payload: Dict[str, Any] = {'externalUsername': external_username}
+        if client_ip:
+            payload['clientIp'] = client_ip
+        if user_agent:
+            payload['userAgent'] = user_agent
+        if display_name:
+            payload['displayName'] = display_name
+        if fallback_vouchers:
+            payload['fallbackVouchers'] = list(fallback_vouchers)
+        if required is not None:
+            payload['required'] = required
+        if cool_off_minutes is not None:
+            payload['coolOffMinutes'] = cool_off_minutes
+        if details:
+            payload['details'] = details
+        if notice_details:
+            payload['noticeDetails'] = notice_details
+        return self._http.post('/recovery/start', payload)
+
+    def status(self, recovery_id: str) -> Dict[str, Any]:
+        """The recovery now, with its receipt chain. Poll it while the user waits."""
+        if not recovery_id:
+            raise TouchQueConfigException('recovery.status() needs the recovery id')
+        return self._http.get(f'/recovery/{quote(recovery_id, safe="")}')
+
+    def list(self, external_username: Optional[str] = None, open: bool = False) -> List[Dict[str, Any]]:
+        """A user's recoveries, or (``open=True``) every running one of your workspace."""
+        if not external_username and not open:
+            raise TouchQueConfigException('recovery.list() needs external_username or open=True')
+        params: Dict[str, Any] = {}
+        if external_username:
+            params['externalUsername'] = external_username
+        if open:
+            params['open'] = 'true'
+        res = self._http.get('/recovery', params)
+        return res.get('recoveries', []) if isinstance(res, dict) else []
+
+    def veto(self, recovery_id: str, by: Optional[str] = None, reason: Optional[str] = None) -> Dict[str, Any]:
+        """Stops a running recovery (e.g. an admin who does not believe it). Does not freeze the user."""
+        if not recovery_id:
+            raise TouchQueConfigException('recovery.veto() needs the recovery id')
+        payload: Dict[str, Any] = {}
+        if by:
+            payload['by'] = by
+        if reason:
+            payload['reason'] = reason
+        return self._http.post(f'/recovery/{quote(recovery_id, safe="")}/veto', payload)

touchque/resources/risk.py

@@ -0,0 +1,141 @@
+"""
+Silent sign-ins: ask TouchQue's risk engine whether a sign-in needs the phone
+at all, and manage the browsers it knows for a user.
+
+A browser becomes known when the user approves a request on the phone (or
+with a passkey) that carried the browser's device-bound key proof
+(``login.request(..., browser_proof=...)``). Later, ``risk.check`` with a
+fresh proof from the same browser answers ``prompt: False`` when nothing about
+the sign-in is new. ``risk.check`` sends nothing to the phone.
+"""
+from typing import Any, Dict, List, Optional
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+_ASSURANCE = ('high', 'normal', 'low')
+
+
+def parse_risk_check(raw: Any) -> Dict[str, Any]:
+    """Reads a ``POST /risk/check`` answer, failing closed.
+
+    ``prompt`` is ``False`` ONLY when the answer says exactly ``prompt: false``
+    (a JSON boolean). Anything else, including a missing, ``null``, ``0`` or
+    ``"false"`` value or an answer that is not a JSON object, asks. Malformed
+    ``reasons`` become ``[]`` (entries without a string ``code`` are dropped, a
+    missing ``text`` is ``''``), an unknown or missing ``assurance`` is
+    ``'normal'``, and ``silentMode`` is ``'shadow'`` or ``'enforce'``.
+    """
+    body = raw if isinstance(raw, dict) else {}
+    reasons: List[Dict[str, str]] = []
+    if isinstance(body.get('reasons'), list):
+        for r in body['reasons']:
+            if isinstance(r, dict) and isinstance(r.get('code'), str):
+                text = r.get('text')
+                reasons.append({'code': r['code'], 'text': text if isinstance(text, str) else ''})
+    assurance = body.get('assurance')
+    out = {
+        # `is not False`: only the boolean False skips the push (0, None, 'false' ask).
+        'prompt': body.get('prompt') is not False,
+        'reasons': reasons,
+        'assurance': assurance if isinstance(assurance, str) and assurance in _ASSURANCE else 'normal',
+        'silentMode': 'shadow' if body.get('silentMode') == 'shadow' else 'enforce',
+    }
+    # "Why?": the check's case code (K7P-2QX), to show the user.
+    if isinstance(body.get('caseCode'), str):
+        out['caseCode'] = body['caseCode']
+    return out
+
+
+class Risk:
+    """Silent sign-ins: should this sign-in ask the phone, and which browsers
+    TouchQue knows for a user."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def check(
+        self,
+        external_username: str,
+        type: str = 'LOGIN',
+        client_ip: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        browser_proof: Optional[str] = None,
+        max_age_seconds: Optional[int] = None,
+        context: Optional[Dict[str, Any]] = None,
+        client_signals: Optional[str] = None,
+        device_risk: Optional[str] = None,
+        device_risk_request_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Should this sign-in ask the phone? Sends nothing to the phone.
+
+        Returns ``{'prompt', 'reasons', 'assurance', 'silentMode'}``. Skip the
+        push only when ``prompt`` is ``False``; on any error, ask as usual::
+
+            browser_proof = request.headers.get('X-TouchQue-Browser')
+            risk = tq.risk.check(user, client_ip=ip, browser_proof=browser_proof)
+            if risk['prompt'] is False:
+                return sign_in(user)  # known browser, nothing new
+            tq.login.request(user, type='LOGIN', browser_proof=browser_proof)
+
+        :param type: the action the user is about to do (default ``'LOGIN'``).
+            A critical action always asks.
+        :param client_ip: the end user's IP address, compared with the networks
+            of the user's earlier approved sign-ins.
+        :param browser_proof: the browser's device-bound key proof
+            (``X-TouchQue-Browser``), passed through untouched.
+        :param max_age_seconds: your own limit on how long ago the last phone
+            approval in this browser may be (integer, ``0`` = always ask).
+            TouchQue never goes beyond its own limit (7 days).
+        :param context: for your TouchQue Actions only (``event.context``).
+        :param client_signals: the end user's page check from ``@touchque/web``
+            (``startClientSignals().encode()``): software driving the browser is never silent.
+        :param device_risk: the page's device report from ``@touchque/web``
+            (``deviceRisk.collect({ purpose: 'sign_in' })``): a device signal is never silent.
+        :param device_risk_request_id: the page's identification (``deviceRisk.identify()``), preferred.
+        """
+        if not external_username:
+            raise TouchQueConfigException('risk.check() needs the user (external_username)')
+        payload: Dict[str, Any] = {'externalUsername': external_username}
+        if type:
+            payload['type'] = type
+        if client_ip:
+            payload['clientIp'] = client_ip
+        if user_agent:
+            payload['userAgent'] = user_agent
+        if browser_proof:
+            payload['browserProof'] = browser_proof
+        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 max_age_seconds is not None:
+            payload['maxAgeSeconds'] = max_age_seconds
+        if context:
+            payload['context'] = context
+        return parse_risk_check(self._http.post('/risk/check', payload))
+
+    def browsers(self, external_username: str) -> Dict[str, Any]:
+        """The browsers TouchQue knows for a user, for an "approved browsers"
+        list in your settings page: ``{'browsers': [{'thumbprint', 'label',
+        'createdAt', 'lastMfaAt', 'lastMfaMethod', 'lastSeenAt',
+        'lastSilentAt'}]}``. Pass a ``thumbprint`` to ``forget_browsers`` to
+        forget that one."""
+        if not external_username:
+            raise TouchQueConfigException('risk.browsers() needs the user (external_username)')
+        res = self._http.get('/risk/browsers', {'externalUsername': external_username})
+        browsers = res.get('browsers') if isinstance(res, dict) else None
+        return {'browsers': browsers if isinstance(browsers, list) else []}
+
+    def forget_browsers(self, external_username: str, thumbprint: Optional[str] = None) -> Dict[str, Any]:
+        """Forgets one browser (``thumbprint``) or all of a user's browsers:
+        their next sign-in asks the phone again. Call it after a password reset
+        or when the user signs out everywhere. Returns ``{'forgotten': n}``."""
+        if not external_username:
+            raise TouchQueConfigException('risk.forget_browsers() needs the user (external_username)')
+        payload: Dict[str, Any] = {'externalUsername': external_username}
+        if thumbprint:
+            payload['thumbprint'] = thumbprint
+        return self._http.post('/risk/browsers/forget', payload)

touchque/resources/safe_guard.py

@@ -0,0 +1,99 @@
+"""Safe Guard: a Safe transaction approved on the approver's phone for TouchQueSafeGuard (the
+guard on your Safe). You send the raw transaction; the phone gets the raw fields only, decodes
+them itself, shows its own rows and signs, with a key only its biometrics unlock, a 105-byte
+approval of the hash it computed. TouchQue never holds a key that can approve.
+
+1. ``request(external_username, type, safe_tx)`` asks the phone (same pipeline as
+   ``login.request``: risk engine, push limit, Vishing Shield, case code, always biometrics).
+2. ``wait_for_approval(request_id)`` (or poll ``status``) until the phone answered.
+3. Check ``safeTx['approval']`` yourself with ``touchque.verify_safe_approval``: it needs your
+   own transaction and the approver's key from the guard, not this response.
+4. ``purpose == 'approve'``: ``with_safe_approvals(owner_signatures, approvals)`` as the
+   signatures of ``execTransaction``. ``purpose == 'schedule'``: send
+   ``safe_schedule_call(safe, governance_hash, approvals)`` to the guard; the change runs once its
+   waiting time is over.
+"""
+import time
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+from ..exceptions import TouchQueConfigException, TouchQueRejectedException, TouchQueTimeoutException
+from ..http_client import HttpClient
+
+_NUMBERS = ('value', 'safeTxGas', 'baseGas', 'gasPrice', 'nonce')
+
+
+def _wire(safe_tx: Mapping[str, Any]) -> Dict[str, Any]:
+    """Large integers go as decimal strings, as the API takes them."""
+    out = dict(safe_tx)
+    if isinstance(out.get('chainId'), int):
+        out['chainId'] = str(out['chainId'])
+    tx = dict(out['tx'])
+    for name in _NUMBERS:
+        if isinstance(tx.get(name), int) and not isinstance(tx.get(name), bool):
+            tx[name] = str(tx[name])
+    out['tx'] = tx
+    return out
+
+
+class SafeGuard:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def request(self, external_username: str, type: str, safe_tx: Mapping[str, Any], reference_id: Optional[str] = None,
+                expires_in: Optional[int] = None, client_ip: Optional[str] = None, user_agent: Optional[str] = None) -> Dict[str, Any]:
+        """Asks the approver's phone to approve a Safe transaction.
+
+        ``type``: an action type from your dashboard. ``safe_tx``: ``{"chainId", "safe", "guard",
+        "tx": {"to", "value", "data", "operation", "safeTxGas", "baseGas", "gasPrice", "gasToken",
+        "refundReceiver", "nonce"}, "config": {"threshold", "govThreshold", "govDelay", "exitDelay",
+        "recipientLock"}, "batchTargets", "recipients", "approverIndex", "locale"}``.
+        ``expires_in``: seconds, 30 to 300 (default 300)::
+
+            sent = tq.safe_guard.request('treasurer@acme.com', 'safe_payment', {
+                'chainId': 1, 'safe': SAFE, 'guard': GUARD,
+                'tx': {'to': to, 'value': 0, 'data': data, 'operation': 0, 'nonce': 42},
+                'config': {'threshold': 2, 'govThreshold': 3, 'govDelay': 172800, 'exitDelay': 259200},
+                'approverIndex': 0,
+            })
+        """
+        if not external_username:
+            raise TouchQueConfigException('safe_guard.request() needs external_username.')
+        if not type:
+            raise TouchQueConfigException('safe_guard.request() needs type: an action type from your dashboard.')
+        if not isinstance(safe_tx, Mapping) or not isinstance(safe_tx.get('tx'), Mapping):
+            raise TouchQueConfigException('safe_guard.request() needs safe_tx: {"chainId", "safe", "guard", "tx", "config", "approverIndex"}.')
+        body: Dict[str, Any] = {'externalUsername': external_username, 'type': type, 'safeTx': _wire(safe_tx)}
+        if reference_id:
+            body['referenceId'] = reference_id
+        if expires_in is not None:
+            body['expiresIn'] = expires_in
+        if client_ip:
+            body['clientIp'] = client_ip
+        if user_agent:
+            body['userAgent'] = user_agent
+        return self._http.post('/safe-guard/approvals', body)
+
+    def status(self, request_id: str) -> Dict[str, Any]:
+        """The request's status and, once approved, the approval (``safeTx['approval']``, 105 bytes hex)."""
+        if not request_id:
+            raise TouchQueConfigException('safe_guard.status() needs a request_id.')
+        return self._http.get(f'/safe-guard/approvals/{quote(request_id, safe="")}')
+
+    def wait_for_approval(self, request_id: str, timeout_ms: int = 300000, poll_interval_ms: int = 1500) -> Dict[str, Any]:
+        """Polls until the phone approved and returns the status with the approval.
+
+        Raises ``TouchQueRejectedException`` when the person said no, ``TouchQueTimeoutException``
+        when it expired or ``timeout_ms`` (default 5 minutes, the request's own life) ran out."""
+        start = time.monotonic()
+        while True:
+            status = self.status(request_id)
+            if status.get('status') == 'CONFIRMED':
+                return status
+            if status.get('status') == 'REJECTED':
+                raise TouchQueRejectedException(f'Request {request_id} was rejected by the user.')
+            if status.get('status') == 'EXPIRED':
+                raise TouchQueTimeoutException(f'Request {request_id} expired before it was approved.')
+            if (time.monotonic() - start) * 1000 > timeout_ms:
+                raise TouchQueTimeoutException(f'Safe Guard approval timed out after {timeout_ms}ms')
+            time.sleep(poll_interval_ms / 1000)

touchque/resources/webauthn.py

@@ -0,0 +1,115 @@
+from typing import Dict, Any, Optional
+from urllib.parse import quote
+from ..http_client import HttpClient
+
+
+class WebAuthn:
+    """
+    WebAuthn / FIDO2 (passkey) — a phishing-resistant approval path alongside
+    the push + device flow (``login.verify``).
+
+    Server-to-server, like every other resource here: the passkey ceremony runs
+    in the browser (``navigator.credentials.create()`` / ``.get()``, or
+    ``@touchque/web``), your backend collects that JSON and relays it through
+    these methods. There is no client-side ceremony in this SDK.
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    # ── registration ────────────────────────────────────────────────────────
+    def register_options(self, external_username: str, discoverable: bool = False,
+                         approval_request_id: Optional[str] = None) -> Dict[str, Any]:
+        """Step 1: options for ``navigator.credentials.create()``.
+
+        ``discoverable=True`` registers a resident credential with forced user
+        verification — the shape a passwordless-primary login authenticates
+        against. Omit for a classic second-factor credential.
+
+        ``approval_request_id`` is required when the user has a linked phone
+        (the API answers 403 ``enrollment_approval_required`` otherwise): a
+        ``PASSKEY_ENROLL`` request the user approved on the phone, at most 10
+        minutes old, used once. The relay's /passkey/register/options runs
+        that approval for you.
+        """
+        body: Dict[str, Any] = {'externalUsername': external_username}
+        if discoverable:
+            body['discoverable'] = True
+        if approval_request_id:
+            body['approvalRequestId'] = approval_request_id
+        return self._http.post('/webauthn/register/options', body)
+
+    def register_verify(self, external_username: str, response: Dict[str, Any], label: Optional[str] = None) -> Dict[str, Any]:
+        """Step 2: verify the browser's registration response and store the credential.
+
+        Returns ``{ verified, credentialId }``.
+        """
+        body: Dict[str, Any] = {'externalUsername': external_username, 'response': response}
+        if label:
+            body['label'] = label
+        return self._http.post('/webauthn/register/verify', body)
+
+    # ── second-factor authentication (against a pending LoginRequest) ────────
+    def authenticate_options(self, request_id: str) -> Dict[str, Any]:
+        """Step 1: options for ``navigator.credentials.get()``, scoped to a
+        pending ``request_id`` from ``login.request()``."""
+        return self._http.post('/webauthn/login/options', {'requestId': request_id})
+
+    def authenticate_verify(self, request_id: str, response: Dict[str, Any]) -> Dict[str, Any]:
+        """Step 2: verify the assertion — approves the LoginRequest on success.
+
+        Returns ``{ success, message }``.
+        """
+        return self._http.post('/webauthn/login/verify', {'requestId': request_id, 'response': response})
+
+    # ── passwordless-primary login (no password, no prior login.request) ────
+    def primary_availability(self) -> Dict[str, Any]:
+        """Whether passkey sign-in (``TenantPolicy.passwordlessLoginEnabled``)
+        is on for your workspace. Ask before your sign-in page shows its passkey
+        button and passkey autofill: when it is off, ``primary_options`` answers
+        403 ``passwordless_login_disabled``. Read-only.
+
+        Returns ``{ enabled, userVerification }`` (``userVerification`` is
+        ``'required'``, ``'preferred'``, or ``None`` when off).
+        """
+        raw = self._http.get('/webauthn/authenticate/primary/availability') or {}
+        enabled = raw.get('enabled') is True
+        uv = raw.get('userVerification')
+        return {'enabled': enabled, 'userVerification': uv if enabled and uv in ('required', 'preferred') else None}
+
+    def primary_options(self, external_username: Optional[str] = None) -> Dict[str, Any]:
+        """Step 1 of a passwordless-primary login. Requires
+        ``TenantPolicy.passwordlessLoginEnabled``. A 404 ``no_passkey_registered``
+        means the user has no passkey — fall back to password login.
+
+        Without ``external_username`` the options accept any passkey of your
+        site (passkey autofill, where nobody has typed an email yet), and
+        ``primary_verify`` names the user the passkey belongs to.
+
+        Returns ``{ attemptId, options }``.
+        """
+        body = {'externalUsername': external_username} if external_username else {}
+        return self._http.post('/webauthn/authenticate/primary/options', body)
+
+    def primary_verify(self, attempt_id: str, response: Dict[str, Any]) -> Dict[str, Any]:
+        """Step 2 of a passwordless-primary login.
+
+        On ``success=True`` the returned ``requestId`` is a CONFIRMED
+        LoginRequest. On ``success=False`` with ``requiresStepUp=True``, start
+        the normal ``login.request()`` / number-match flow instead.
+        """
+        return self._http.post('/webauthn/authenticate/primary/verify', {'attemptId': attempt_id, 'response': response})
+
+    # ── credential management ──────────────────────────────────────────────
+    def list_credentials(self, external_username: str) -> Dict[str, Any]:
+        """List a user's registered credentials (metadata only, no key material)."""
+        return self._http.get('/webauthn/credentials', params={'externalUsername': external_username})
+
+    def delete_credential(self, credential_record_id: str, external_username: Optional[str] = None) -> Dict[str, Any]:
+        """Remove a registered credential. Pass ``external_username`` to scope
+        the deletion to that user (recommended: without it, any credential id
+        your API key can reach is deletable). Returns ``{ deleted: bool }``."""
+        path = f"/webauthn/credentials/{quote(credential_record_id, safe='')}"
+        if external_username:
+            path += f"?externalUsername={quote(external_username, safe='')}"
+        return self._http.delete(path)