touchque-authenticator 4.2.0__py3-none-any.whl

touchque/agent_frameworks.py

@@ -0,0 +1,215 @@
+"""A person approves an AI agent's tool call on their phone before it runs, in
+whichever agent framework the agent is built with.
+
+One rule, an ``ApprovalPolicy``, says who approves (``user``), as which action
+type, and what the phone shows (``details``: RFC 9396 authorization details
+drawn from the tool's arguments). TouchQue draws the rows, the person types the
+number the conversation shows and confirms with Face ID, and the call runs only
+once they approved. The approval token (single use, bound to exactly what was
+approved) is there for the service that executes: ``current_approval()`` inside
+the tool, or the MCP request's ``_meta``::
+
+    policy = ApprovalPolicy(agent, user='ada@acme.com', type='PAY_INVOICE',
+                            details=lambda args, tool: [{'type': 'payment_initiation',
+                                                         'instructedAmount': {'currency': 'TRY', 'amount': args['amount']},
+                                                         'creditorAccount': {'iban': args['iban']}}],
+                            on_challenge=lambda state, tool: reply(f"Type {state['challengeCode']} in the TouchQue app."))
+
+    @with_touchque_approval(policy)
+    def pay(iban: str, amount: str) -> str:
+        return bank.pay(iban, amount, current_approval()['approvalToken'])
+
+The decorated function keeps its signature, so LangChain's ``@tool``,
+LlamaIndex's ``FunctionTool.from_defaults`` and the OpenAI Agents SDK's
+``@function_tool`` read the same arguments (async functions work too). For
+frameworks with their own approval step: ``approve_interruptions_with_touchque``
+(OpenAI Agents SDK), ``touchque_can_use_tool`` (Claude Agent SDK) and
+``guard_mcp_session`` (an MCP ClientSession).
+"""
+
+import asyncio
+import contextvars
+import functools
+import inspect
+import json
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .exceptions import TouchQueApprovalError, TouchQueTimeoutException
+
+_current: contextvars.ContextVar = contextvars.ContextVar('touchque_approval', default=None)
+
+Pick = Union[str, Callable[[Dict[str, Any], str], str]]
+
+
+class ApprovalPolicy:
+    """Who approves which tool calls, and what their phone shows."""
+
+    def __init__(self, agent, user: Pick, type: Pick, details: Callable[[Dict[str, Any], str], List[Dict[str, Any]]],
+                 reason: Optional[Pick] = None, presence: Optional[str] = None, locale: Optional[str] = None,
+                 mandate_id: Optional[str] = None, on_challenge: Optional[Callable[[Dict[str, Any], str], Any]] = None,
+                 timeout: float = 300):
+        self.agent = agent
+        self.user = user
+        self.type = type
+        self.details = details
+        self.reason = reason
+        self.presence = presence
+        self.locale = locale
+        self.mandate_id = mandate_id
+        self.on_challenge = on_challenge
+        self.timeout = timeout
+
+
+async def _to_thread(fn, *args):
+    """``asyncio.to_thread`` (Python 3.9+), also on 3.7 and 3.8: the blocking wait for the phone
+    runs in the loop's default executor, with this context's variables."""
+    if hasattr(asyncio, 'to_thread'):
+        return await asyncio.to_thread(fn, *args)
+    ctx = contextvars.copy_context()
+    return await asyncio.get_running_loop().run_in_executor(None, functools.partial(ctx.run, fn, *args))
+
+
+def current_approval() -> Optional[Dict[str, Any]]:
+    """Inside a tool wrapped by ``with_touchque_approval``: the approval it runs under."""
+    return _current.get()
+
+
+def _pick(value, args: Dict[str, Any], tool: str):
+    return value(args, tool) if callable(value) else value
+
+
+def require_agent_approval(policy: ApprovalPolicy, args: Dict[str, Any], tool: str = 'tool') -> Dict[str, Any]:
+    """Asks the person's phone and waits: the approved state (with ``approvalToken``),
+    or TouchQueApprovalError (rejected, blocked, expired...) / TouchQueTimeoutException."""
+    asked = policy.agent.request_approval(
+        _pick(policy.user, args, tool), _pick(policy.type, args, tool), policy.details(args, tool),
+        reason=_pick(policy.reason, args, tool) if policy.reason is not None else None,
+        presence=policy.presence, locale=policy.locale, mandate_id=policy.mandate_id,
+    )
+    if asked.get('status') == 'approved' and asked.get('approvalToken'):
+        return asked
+    if asked.get('challengeCode') and policy.on_challenge:
+        policy.on_challenge(asked, tool)
+    return policy.agent.wait_for_approval(asked['approvalId'], timeout=policy.timeout)
+
+
+def _bound_args(fn, args, kwargs) -> Dict[str, Any]:
+    try:
+        bound = inspect.signature(fn).bind_partial(*args, **kwargs)
+        return dict(bound.arguments)
+    except (TypeError, ValueError):
+        return dict(kwargs)
+
+
+def with_touchque_approval(policy: ApprovalPolicy, tool: Optional[str] = None):
+    """Decorator: the function runs only after the person approved on the phone;
+    ``current_approval()`` is set while it runs. Works on plain and async functions."""
+
+    def wrap(fn):
+        name = tool or fn.__name__
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def run_async(*args, **kwargs):
+                approval = await _to_thread(require_agent_approval, policy, _bound_args(fn, args, kwargs), name)
+                token = _current.set(approval)
+                try:
+                    return await fn(*args, **kwargs)
+                finally:
+                    _current.reset(token)
+            return run_async
+
+        @functools.wraps(fn)
+        def run(*args, **kwargs):
+            approval = require_agent_approval(policy, _bound_args(fn, args, kwargs), name)
+            token = _current.set(approval)
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                _current.reset(token)
+        return run
+
+    return wrap
+
+
+def _args_of(raw) -> Dict[str, Any]:
+    if isinstance(raw, str):
+        try:
+            return json.loads(raw)
+        except ValueError:
+            return {}
+    return raw or {}
+
+
+def approve_interruptions_with_touchque(result, policies: Dict[str, ApprovalPolicy]):
+    """OpenAI Agents SDK: tools with ``needs_approval`` interrupt the run; this asks the
+    phone for each interruption in ``policies`` (by tool name) and approves or rejects it
+    on the run state. Returns the state to resume with ``Runner.run(agent, state)``."""
+    state = result.to_state() if hasattr(result, 'to_state') else result.state
+    for item in getattr(result, 'interruptions', None) or []:
+        raw = getattr(item, 'raw_item', None) or getattr(item, 'rawItem', None) or item
+        name = getattr(raw, 'name', None) or (raw.get('name') if isinstance(raw, dict) else None)
+        policy = policies.get(name)
+        if not policy:
+            continue
+        arguments = getattr(raw, 'arguments', None) if not isinstance(raw, dict) else raw.get('arguments')
+        try:
+            require_agent_approval(policy, _args_of(arguments), name)
+            state.approve(item)
+        except (TouchQueApprovalError, TouchQueTimeoutException):
+            state.reject(item)
+    return state
+
+
+def touchque_can_use_tool(policies: Dict[str, ApprovalPolicy], token_field: Optional[str] = None, deny_others: bool = False):
+    """Claude Agent SDK: a ``can_use_tool`` callback. Tools with a policy run only after
+    the phone approved (``token_field``: put the approval token into the tool's input);
+    others are allowed or, with ``deny_others``, denied."""
+    try:
+        from claude_agent_sdk import PermissionResultAllow, PermissionResultDeny  # type: ignore
+    except ImportError:  # the SDK's own result types when installed, plain dicts otherwise
+        PermissionResultAllow = PermissionResultDeny = None
+
+    def allow(updated):
+        return PermissionResultAllow(updated_input=updated) if PermissionResultAllow else {'behavior': 'allow', 'updatedInput': updated}
+
+    def deny(message):
+        return PermissionResultDeny(message=message) if PermissionResultDeny else {'behavior': 'deny', 'message': message}
+
+    async def can_use_tool(tool_name: str, input_data: Dict[str, Any], context: Any = None):
+        policy = policies.get(tool_name)
+        if not policy:
+            return deny(f'{tool_name} is not allowed for this agent') if deny_others else allow(input_data)
+        try:
+            approval = await _to_thread(require_agent_approval, policy, input_data, tool_name)
+        except (TouchQueApprovalError, TouchQueTimeoutException) as err:
+            return deny(f"The person did not approve {tool_name} on their phone ({getattr(err, 'status', 'timeout')})")
+        return allow({**input_data, token_field: approval.get('approvalToken')} if token_field else input_data)
+
+    return can_use_tool
+
+
+class _GuardedSession:
+    def __init__(self, session, policies: Dict[str, ApprovalPolicy]):
+        self._session = session
+        self._policies = policies
+
+    def __getattr__(self, name):
+        return getattr(self._session, name)
+
+    async def call_tool(self, name: str, arguments: Optional[Dict[str, Any]] = None, *args, **kwargs):
+        policy = self._policies.get(name)
+        if policy:
+            approval = await _to_thread(require_agent_approval, policy, arguments or {}, name)
+            meta = dict(kwargs.pop('meta', None) or {})
+            meta['touchque/approvalToken'] = approval.get('approvalToken')
+            try:
+                return await self._session.call_tool(name, arguments, *args, meta=meta, **kwargs)
+            except TypeError:  # an MCP SDK too old to send _meta: the call still waited for the phone
+                return await self._session.call_tool(name, arguments, *args, **kwargs)
+        return await self._session.call_tool(name, arguments, *args, **kwargs)
+
+
+def guard_mcp_session(session, policies: Dict[str, ApprovalPolicy]):
+    """An MCP ``ClientSession``: the tools in ``policies`` are called only after the phone
+    approved; the approval token goes to the server in ``_meta`` ("touchque/approvalToken")."""
+    return _GuardedSession(session, policies)

touchque/approval_proof.py

@@ -0,0 +1,104 @@
+"""Verifies the device-signed proof of an approval ("what you see is what you sign").
+
+When the user's phone holds a hardware key (Secure Enclave / Android Keystore),
+every approval is signed by it over the request id, the action type, the
+number-match code and a digest of the transaction details the user was shown.
+The proof arrives in the SUCCESS webhook (``approvalProof``) and in
+``login.status(id)['approvalProof']``. Verifying it does not require trusting
+TouchQue: it proves the enrolled phone signed exactly these details.
+
+Needs the optional ``cryptography`` package:
+``pip install "touchque-authenticator[proof]"``.
+"""
+import base64
+import binascii
+from typing import Any, Mapping, Optional
+
+from .steps import LoginDetails, details_digest
+
+__all__ = ['verify_approval_proof', 'details_digest']
+
+_MESSAGE_PREFIX = 'touchque-approve:v2'
+
+
+def _load_crypto():
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError(
+            'verify_approval_proof needs the "cryptography" package: '
+            'pip install "touchque-authenticator[proof]"'
+        ) from exc
+    return InvalidSignature, hashes, ec
+
+
+def verify_approval_proof(
+    proof: Optional[Mapping[str, Any]],
+    *,
+    request_id: str,
+    type: str,
+    details: Optional[LoginDetails] = None,
+    challenge_code: Optional[str] = None,
+    expected_public_key: Optional[str] = None,
+    allow_unpinned_key: bool = False,
+) -> bool:
+    """Returns True only if ``proof`` was signed by the device key over exactly
+    the request, action type, challenge code and details you expect.
+
+    :param proof: the ``approvalProof`` object from the webhook / status.
+    :param request_id: the request id ``login.request()`` returned.
+    :param type: the action type you sent (e.g. ``'WITHDRAW'``).
+    :param details: the details you sent, exactly as you sent them (dict or
+        list of ``{label, value}``); ``None`` when you sent none.
+    :param challenge_code: the number-match code ``login.request()`` returned,
+        when number matching was used.
+    :param expected_public_key: pin the device — the base64 public key you
+        stored for this user (e.g. ``proof['publicKey']`` of their first
+        verified approval). A proof from any other key is rejected. Required
+        unless ``allow_unpinned_key`` is set.
+    :param allow_unpinned_key: accept whatever key the proof carries. Without a
+        pinned key the proof only shows that *some* key signed these details.
+        Only for trust-on-first-use: store ``proof['publicKey']`` after this
+        first check and pin it from then on.
+
+    Fails closed (no pin and no ``allow_unpinned_key`` -> False) and never
+    raises for malformed input; it returns False.
+    """
+    InvalidSignature, hashes, ec = _load_crypto()
+    try:
+        if not isinstance(proof, Mapping):
+            return False
+        if proof.get('version') != 'v2' or proof.get('algorithm') != 'ECDSA-P256-SHA256':
+            return False
+        public_key_b64 = proof.get('publicKey')
+        message = proof.get('message')
+        signature_b64 = proof.get('signature')
+        if not all(isinstance(v, str) for v in (public_key_b64, message, signature_b64)):
+            return False
+        if expected_public_key:
+            if public_key_b64 != expected_public_key:
+                return False
+        elif allow_unpinned_key is not True:
+            return False
+
+        expected_message = '\n'.join([
+            _MESSAGE_PREFIX,
+            str(request_id),
+            str(type),
+            challenge_code if challenge_code is not None else '',
+            details_digest(details),
+        ])
+        if message != expected_message:
+            return False
+
+        raw = base64.b64decode(public_key_b64, validate=True)
+        if len(raw) != 65 or raw[0] != 0x04:
+            return False
+        key = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), raw)
+        signature = base64.b64decode(signature_b64, validate=True)
+        key.verify(signature, message.encode('utf-8'), ec.ECDSA(hashes.SHA256()))
+        return True
+    except (InvalidSignature, ValueError, TypeError, binascii.Error):
+        return False

touchque/approval_token.py

@@ -0,0 +1,134 @@
+"""What a partner's server checks before executing what an AI agent asked
+for: the approval token's claims match the transaction (person, action type,
+authorization details), and, offline, its ES256 signature against TouchQue's
+keys (GET /agents/jwks.json).
+
+Matching rules (fixtures/agent-vectors.json): every expected field must be
+equal, extra fields are ignored; amounts compare as decimals ("500" =
+"500.00"), IBANs without spaces and in any case, currencies in any case; a
+dict matches a token with exactly one entry, a list matches entry by entry
+with the same length.
+"""
+import base64
+import json
+import re
+import time
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from .exceptions import TouchQueApprovalMismatchError
+
+__all__ = ['matches_authorization_details', 'assert_approval_matches', 'decode_approval_token', 'verify_approval_token_with']
+
+Expected = Union[Mapping[str, Any], List[Mapping[str, Any]]]
+
+
+def _decimal(value: Any) -> Optional[str]:
+    text = str(value).strip()
+    if not re.match(r'^\d+(\.\d+)?$', text):
+        return None
+    whole, _, frac = text.partition('.')
+    whole = whole.lstrip('0') or '0'
+    frac = frac.rstrip('0')
+    return f'{whole}.{frac}' if frac else whole
+
+
+def _same(key: str, actual: Any, expected: Any) -> bool:
+    if isinstance(expected, (dict, list)):
+        return _partial(actual, expected)
+    if key == 'amount':
+        return _decimal(actual) is not None and _decimal(actual) == _decimal(expected)
+    if key in ('iban', 'currency'):
+        return isinstance(actual, str) and re.sub(r'\s+', '', actual).upper() == re.sub(r'\s+', '', str(expected)).upper()
+    return actual == expected and type(actual) is type(expected)
+
+
+def _partial(actual: Any, expected: Any) -> bool:
+    if isinstance(expected, list):
+        return isinstance(actual, list) and len(actual) == len(expected) and all(
+            _partial(a, e) if isinstance(e, dict) else a == e for a, e in zip(actual, expected))
+    if not isinstance(actual, dict):
+        return False
+    return all(k in actual and _same(k, actual[k], v) for k, v in expected.items())
+
+
+def matches_authorization_details(details: Any, expected: Expected) -> bool:
+    """Does ``details`` (a token's authorization_details) say what ``expected`` says?"""
+    if not isinstance(details, list):
+        return False
+    if isinstance(expected, list):
+        return len(details) == len(expected) and all(_partial(d, e) for d, e in zip(details, expected))
+    return len(details) == 1 and _partial(details[0], expected)
+
+
+def assert_approval_matches(claims: Mapping[str, Any], user: Optional[str] = None, type: Optional[str] = None,
+                            authorization_details: Optional[Expected] = None) -> None:
+    """Raises TouchQueApprovalMismatchError unless the claims say what you expect."""
+    if user is not None and claims.get('sub') != user:
+        raise TouchQueApprovalMismatchError("the approval is for another person")
+    if type is not None and claims.get('type') != type:
+        raise TouchQueApprovalMismatchError(f"the approval is for another action type ({claims.get('type')})")
+    if authorization_details is not None and not matches_authorization_details(claims.get('authorization_details'), authorization_details):
+        raise TouchQueApprovalMismatchError('the approved details differ from what you are about to execute')
+
+
+def _b64(part: str) -> bytes:
+    return base64.urlsafe_b64decode(part + '=' * (-len(part) % 4))
+
+
+def decode_approval_token(token: str) -> Dict[str, Any]:
+    """``{'header': ..., 'claims': ...}`` WITHOUT checking the signature."""
+    parts = token.split('.') if isinstance(token, str) else []
+    if len(parts) != 3:
+        raise TouchQueApprovalMismatchError('not an approval token')
+    try:
+        return {'header': json.loads(_b64(parts[0])), 'claims': json.loads(_b64(parts[1]))}
+    except (ValueError, TypeError) as exc:
+        raise TouchQueApprovalMismatchError('not an approval token') from exc
+
+
+def verify_approval_token_with(token: str, jwks: Mapping[str, Any], audience: Optional[str] = None,
+                               now: Optional[float] = None, **expect: Any) -> Dict[str, Any]:
+    """Verifies an approval token offline: typ touchque-approval+jwt, ES256 by
+    a key of ``jwks``, not expired (30 s leeway), ``aud`` equal to
+    ``audience``, then ``user`` / ``type`` / ``authorization_details``.
+    ``audience`` is required: ``/agents/jwks.json`` is one key set for every
+    Touchque workspace, so without it a token Touchque signed for another
+    workspace would pass. Pass your own (``client.agents.approval_audience()``,
+    ``touchque:workspace:<id>``), or use ``client.agents.verify_approval_token``,
+    which fills it in. Does NOT make it single-use
+    (``client.agents.redeem_approval`` does). Needs ``cryptography``."""
+    if not isinstance(audience, str) or not audience:
+        raise TouchQueApprovalMismatchError("audience is required: your workspace's touchque:workspace:<id> (client.agents.approval_audience())")
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+
+    decoded = decode_approval_token(token)
+    header, claims = decoded['header'], decoded['claims']
+    if header.get('typ') != 'touchque-approval+jwt' or header.get('alg') != 'ES256':
+        raise TouchQueApprovalMismatchError('not an approval token (typ/alg)')
+    jwk = next((k for k in jwks.get('keys', []) if k.get('kid') == header.get('kid') and k.get('kty') == 'EC' and k.get('crv') == 'P-256'), None)
+    if not jwk:
+        raise TouchQueApprovalMismatchError('signed by an unknown key')
+    h, p, s = token.split('.')
+    try:
+        sig = _b64(s)
+    except ValueError:  # not base64url (e.g. non-ASCII): a signature that does not verify
+        sig = b''
+    if len(sig) != 64:
+        raise TouchQueApprovalMismatchError('the signature does not verify')
+    key = ec.EllipticCurvePublicNumbers(int.from_bytes(_b64(jwk['x']), 'big'), int.from_bytes(_b64(jwk['y']), 'big'), ec.SECP256R1()).public_key()
+    try:
+        key.verify(encode_dss_signature(int.from_bytes(sig[:32], 'big'), int.from_bytes(sig[32:], 'big')), f'{h}.{p}'.encode('ascii'), ec.ECDSA(hashes.SHA256()))
+    except InvalidSignature as exc:
+        raise TouchQueApprovalMismatchError('the signature does not verify') from exc
+    current = time.time() if now is None else now
+    if not isinstance(claims.get('exp'), (int, float)) or claims['exp'] + 30 < current:
+        raise TouchQueApprovalMismatchError('the approval token expired')
+    if not isinstance(claims.get('aud'), str) or not claims.get('aud'):
+        raise TouchQueApprovalMismatchError('the approval token names no workspace')
+    if claims['aud'] != audience:
+        raise TouchQueApprovalMismatchError('the approval token is for another workspace')
+    assert_approval_matches(claims, **expect)
+    return claims

touchque/client.py

@@ -0,0 +1,105 @@
+from typing import Any, Dict, Optional
+
+from .config import Config
+from .http_client import HttpClient
+from .resources.action_types import ActionTypes
+from .resources.actions import Actions
+from .resources.agents import Agents
+from .resources.identity import Identity
+from .resources.auth import Auth
+from .resources.login import Login
+from .resources.offline import Offline
+from .resources.risk import Risk
+from .resources.recovery import Recovery
+from .resources.mobile import Mobile
+from .resources.qr_pairings import QrPairings
+from .resources.device_risk import DeviceRisk
+from .resources.safe_guard import SafeGuard
+from .resources.assist import Assist
+from .resources.webauthn import WebAuthn
+from .resources.webhook import Webhook
+from .steps import LoginDetails, check as _check, complete as _complete, start as _start
+
+
+class TouchQue:
+    """
+    TouchQue SDK client.
+
+        # .env: TQ_API_KEY=tq_...  TQ_API_SECRET=...
+        client = TouchQue()                                   # from the environment
+        client = TouchQue(Config(api_key=..., api_secret=...))  # explicit
+
+    One line per protected route (see ``touchque.contrib`` for Django /
+    FastAPI / Flask adapters, or call ``client.start`` / ``client.check`` /
+    ``client.complete`` yourself for any framework).
+    """
+
+    def __init__(self, config: Optional[Config] = None):
+        self.config = config or Config()
+        self._api_secret = self.config.api_secret
+        http = HttpClient(self.config)
+
+        self.auth = Auth(http)
+        self.login = Login(http)
+        self.webauthn = WebAuthn(http)
+        self.webhook = Webhook(self.config)
+        self.offline = Offline(http)
+        #: Action types: what users approve (LOGIN, SEND_MONEY…). Was ``actions`` before 4.0.
+        self.action_types = ActionTypes(http)
+        #: TouchQue Actions: your own code in the approval pipeline.
+        self.actions = Actions(http)
+        #: Silent sign-ins: should this sign-in ask the phone, and which browsers TouchQue knows.
+        self.risk = Risk(http)
+        #: Never Locked Out: move a user whose phone is gone to a new phone, with colleagues vouching.
+        self.recovery = Recovery(http)
+        #: Help desk: IT working on a person's account in the open, and checks on their phone before sensitive actions.
+        self.assist = Assist(http)
+        #: AI agents as identities of their own: register (public key), suspend, revoke, kill switch.
+        #: The agent itself uses ``touchque.TouchQueAgent``.
+        self.agents = Agents(http)
+        # TouchQue Login Management API: customers' accounts, roles, organizations, apps
+        self.identity = Identity(http)
+        #: Mobile SDK: your own iOS/Android app approves for your users (enrollment tokens, devices, settings).
+        self.mobile = Mobile(http)
+        #: Pairing a browser by QR code: the phone that scans it is the one asked to approve.
+        self.qr_pairings = QrPairings(http)
+        #: Device risk: the device on your sign-up, reset, sign-in or approval page (a paid add-on).
+        self.device_risk = DeviceRisk(http)
+        #: Safe Guard: Safe transactions approved on the approver's phone, for TouchQueSafeGuard.
+        self.safe_guard = SafeGuard(http)
+
+    # ── headless step-up (see touchque.steps / touchque.guard) ─────────────
+
+    def start(self, action: str, user: str, details: Optional[LoginDetails] = None,
+              reference_id: Optional[str] = None, ip: Optional[str] = None,
+              user_agent: Optional[str] = None, browser_proof: Optional[str] = None) -> Dict[str, Any]:
+        """Starts an approval and returns immediately — show the step in your
+        UI. ``waiting`` + ``number``: show the number, the user picks it on
+        the phone. ``enroll``: show ``enroll['qrCodeDataUrl']`` so the user
+        links the TouchQue app first. ``browser_proof``: the browser's
+        ``X-TouchQue-Browser`` proof, so the approval makes the browser known
+        (silent sign-ins, see ``risk.check``)."""
+        return _start(self, action, user, details=details, reference_id=reference_id, ip=ip, user_agent=user_agent,
+                      browser_proof=browser_proof)
+
+    def check(self, request_id: str) -> Dict[str, Any]:
+        """Where a started approval is now: waiting, approved, rejected, expired…"""
+        return _check(self, request_id)
+
+    def complete(self, request_id: str, user: str, action: str, details: Optional[LoginDetails] = None,
+                 reference_id: Optional[str] = None) -> Dict[str, Any]:
+        """Uses an approved request exactly once, after checking it is for
+        this user, action and transaction. Call it right before doing the
+        protected thing."""
+        return _complete(self, request_id, user, action, details=details, reference_id=reference_id)
+
+
+_default_client: Optional[TouchQue] = None
+
+
+def get_default_client() -> TouchQue:
+    """The client built from TQ_API_KEY / TQ_API_SECRET, created on first use."""
+    global _default_client
+    if _default_client is None:
+        _default_client = TouchQue()
+    return _default_client

touchque/code_reply.py

@@ -0,0 +1,75 @@
+"""A code the person types back on the phone (``login.request(reply=...)``).
+
+A sign-in code another service sent them (a text message, WhatsApp, e-mail). Each request gets
+a one-time P-256 key pair; its public key goes with the request, the phone encrypts what was
+typed to it, and only you can open it: TouchQue stores and hands back nothing but the
+ciphertext (``login.status(request_id)['reply']['ct']``).
+
+ECDH P-256, HKDF-SHA256 (salt: the request id, info ``touchque-code-reply-v1``), AES-256-GCM
+(additional data ``touchque-code-reply:<request id>``), as
+``v1.<the phone's one-time key, x9.63>.<nonce|ciphertext|tag>``, base64url.
+
+Needs the optional ``cryptography`` package: ``pip install "touchque-authenticator[proof]"``.
+"""
+import base64
+import re
+from typing import Dict, Optional
+
+from .exceptions import TouchQueConfigException
+
+_INFO = b'touchque-code-reply-v1'
+_CT_RE = re.compile(r'^v1\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$')
+_CODE_RE = re.compile(r'^[A-Za-z0-9 -]{4,20}$')
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')
+
+
+def _unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + '=' * (-len(text) % 4))
+
+
+def _crypto():
+    try:
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import ec
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+    except ImportError as e:  # pragma: no cover - depends on the environment
+        raise TouchQueConfigException('Code replies need the cryptography package: pip install "touchque-authenticator[proof]"') from e
+    return hashes, serialization, ec, AESGCM, HKDF
+
+
+def new_code_reply_key() -> Dict[str, str]:
+    """A one-time key pair for one request: send ``public_key`` as ``reply['key']``, keep ``private_key``.
+
+    ``public_key``: the uncompressed P-256 point (65 bytes), base64url. ``private_key``: PKCS#8 DER,
+    base64url; keep it server-side, for this one request.
+    """
+    hashes, serialization, ec, _, _ = _crypto()
+    key = ec.generate_private_key(ec.SECP256R1())
+    public = key.public_key().public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint)
+    private = key.private_bytes(serialization.Encoding.DER, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())
+    return {'public_key': _b64(public), 'private_key': _b64(private)}
+
+
+def open_code_reply(private_key: str, request_id: str, ct: str) -> Optional[str]:
+    """The code the person typed, or ``None`` when ``ct`` does not open with this key for this request."""
+    hashes, serialization, ec, AESGCM, HKDF = _crypto()
+    try:
+        m = _CT_RE.match(str(ct or ''))
+        if not m:
+            return None
+        epk, box = _unb64(m.group(1)), _unb64(m.group(2))
+        if len(epk) != 65 or epk[0] != 4 or len(box) < 12 + 16 + 1:
+            return None
+        priv = serialization.load_der_private_key(_unb64(private_key), password=None)
+        peer = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), epk)
+        shared = priv.exchange(ec.ECDH(), peer)
+        key = HKDF(algorithm=hashes.SHA256(), length=32, salt=str(request_id).encode('utf-8'), info=_INFO).derive(shared)
+        aad = ('touchque-code-reply:%s' % request_id).encode('utf-8')
+        code = AESGCM(key).decrypt(box[:12], box[12:], aad).decode('utf-8').strip()
+        return code if _CODE_RE.match(code) else None
+    except Exception:  # noqa: BLE001 - anything wrong is "does not open"
+        return None