touchque-authenticator 4.2.0__py3-none-any.whl

touchque/resources/webhook.py

@@ -0,0 +1,258 @@
+import json
+import time
+import hmac
+import hashlib
+import threading
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from ..config import Config
+from ..exceptions import TouchQueWebhookReplayException, TouchQueWebhookSignatureException
+
+# Default replay window: reject a callback whose signed `timestamp` is more
+# than this many seconds away from now. Matches the server's replay guard.
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+class WebhookReasons:
+    """``reason`` values of a REJECTED login webhook. Treat a value you do not
+    know as a rejection: new ones are added in minor versions."""
+    USER_REJECTED = 'user_rejected'
+    #: The user said "this wasn't me": 2FA is frozen.
+    USER_REPORTED_FRAUD = 'user_reported_fraud'
+    #: The user said someone on the phone told them to approve: 2FA is frozen; treat it as a takeover in progress.
+    USER_REPORTED_COACHED = 'user_reported_coached'
+    #: An AI agent's request: the user said no and blocked the agent from asking them again (no 2FA freeze).
+    USER_BLOCKED_AGENT = 'user_blocked_agent'
+    RISK_REVERSED = 'risk_reversed'
+    RISK_STEP_UP = 'risk_step_up'
+    APPROVAL_SIGNATURE_INVALID = 'approval_signature_invalid'
+    DEVICE_INTEGRITY_FAILED = 'device_integrity_failed'
+    #: Vishing Shield: approved during a call (or with the screen shared / remote-controlled), critical, no passkey.
+    VISHING_SUSPECTED = 'vishing_suspected'
+    #: Mirror Alarm: the sign-in page was not on your site (a real-time phishing proxy).
+    PHISHING_ORIGIN = 'phishing_origin'
+
+
+class WebhookEvents:
+    """``event`` values of TouchQue's event webhooks. Ignore types you do not know."""
+    DEVICE_LINKED = 'DEVICE_LINKED'
+    DEVICE_UNLINKED = 'DEVICE_UNLINKED'
+    PASSKEY_REGISTERED = 'PASSKEY_REGISTERED'
+    PASSKEY_DELETED = 'PASSKEY_DELETED'
+    #: Device risk: an identification or a device_risk.check raised a signal that asks for more. Never a trait.
+    DEVICE_RISK_SIGNAL = 'DEVICE_RISK_SIGNAL'
+    #: Device risk: an alert rule of the workspace went off.
+    DEVICE_RISK_ALERT = 'DEVICE_RISK_ALERT'
+    #: After the call, the user confirmed a provisional approval was theirs: critical actions are allowed again.
+    APPROVAL_RECONFIRMED = 'APPROVAL_RECONFIRMED'
+    #: The user took an approval back (``reason``: ``COACHED`` or ``UNDO``): end the session built on it.
+    APPROVAL_REVOKED = 'APPROVAL_REVOKED'
+    # AI agents (client.agents): changes partners may act on, and what TouchQue noticed.
+    #: An AI agent was registered.
+    AGENT_CREATED = 'AGENT_CREATED'
+    #: An AI agent was suspended (through the API or the dashboard): its tokens stopped working.
+    AGENT_SUSPENDED = 'AGENT_SUSPENDED'
+    #: An AI agent may act again.
+    AGENT_RESUMED = 'AGENT_RESUMED'
+    #: An AI agent was revoked for good.
+    AGENT_REVOKED = 'AGENT_REVOKED'
+    #: A key was added to an AI agent.
+    AGENT_KEY_ADDED = 'AGENT_KEY_ADDED'
+    #: A key was removed from an AI agent; tokens bound to it stopped working.
+    AGENT_KEY_REMOVED = 'AGENT_KEY_REMOVED'
+    #: The kill switch stopped every AI agent of the workspace.
+    AGENTS_PAUSED = 'AGENTS_PAUSED'
+    #: The kill switch was turned off.
+    AGENTS_RESUMED = 'AGENTS_RESUMED'
+    #: An AI agent's policy changed.
+    AGENT_POLICY_CHANGED = 'AGENT_POLICY_CHANGED'
+    AGENT_WORKSPACE_POLICY_CHANGED = 'AGENT_WORKSPACE_POLICY_CHANGED'
+    #: An approval token was used.
+    AGENT_APPROVAL_REDEEMED = 'AGENT_APPROVAL_REDEEMED'
+    #: A person stopped an AI agent from asking them ("this wasn't me", coached, or three rejections).
+    AGENT_BLOCKED_BY_PERSON = 'AGENT_BLOCKED_BY_PERSON'
+    #: An admin let an AI agent ask a person again.
+    AGENT_UNBLOCKED_FOR_PERSON = 'AGENT_UNBLOCKED_FOR_PERSON'
+    #: An AI agent sent the same request to the same person three times in 10 minutes.
+    AGENT_LOOP_DETECTED = 'AGENT_LOOP_DETECTED'
+    #: An AI agent asked a person for a mandate.
+    AGENT_MANDATE_REQUESTED = 'AGENT_MANDATE_REQUESTED'
+    #: A mandate was ended.
+    AGENT_MANDATE_REVOKED = 'AGENT_MANDATE_REVOKED'
+    #: An AI agent's text carried an instruction to the model or a link that carries data; the request was refused.
+    AGENT_INJECTION_SUSPECTED = 'AGENT_INJECTION_SUSPECTED'
+    #: An approval came back sooner than a person can answer; it is never usable.
+    AGENT_INHUMAN_APPROVAL = 'AGENT_INHUMAN_APPROVAL'
+    #: A new or renamed AI agent's name read like another agent's; it was refused.
+    AGENT_LOOKALIKE_NAME = 'AGENT_LOOKALIKE_NAME'
+    #: Mobile SDK: send this push with your own keys (``mobile_push_from_webhook``).
+    MOBILE_PUSH = 'MOBILE_PUSH'
+    # Never Locked Out (client.recovery): every step of a recovery.
+    #: A recovery started; the vouchers were asked.
+    RECOVERY_STARTED = 'RECOVERY_STARTED'
+    #: The new phone was bound to the recovery.
+    RECOVERY_DEVICE_BOUND = 'RECOVERY_DEVICE_BOUND'
+    #: The vouchers' quorum was reached: the account moves at ``coolOffUntil`` unless vetoed.
+    RECOVERY_COOLING = 'RECOVERY_COOLING'
+    #: The account moved to the new phone (``method``: ``vouch`` or ``old_phone``); ``DEVICE_LINKED`` follows.
+    RECOVERY_COMPLETED = 'RECOVERY_COMPLETED'
+    #: The recovery was stopped (the old phone, an admin or a voucher).
+    RECOVERY_VETOED = 'RECOVERY_VETOED'
+    #: The recovery ended unused (``reason``: ``not_bound`` in time, or ``replaced`` by a new one).
+    RECOVERY_EXPIRED = 'RECOVERY_EXPIRED'
+    #: The recovery ended without a move (``reason``, e.g. ``not_enough_approvals``).
+    RECOVERY_FAILED = 'RECOVERY_FAILED'
+    # Help desk (client.assist): IT working on a person's account.
+    #: A help desk agent started working on the account.
+    ASSIST_OPENED = 'ASSIST_OPENED'
+    #: The help desk session ended.
+    ASSIST_ENDED = 'ASSIST_ENDED'
+    #: The person confirmed the help desk's check on their phone.
+    ASSIST_CHECK_PASSED = 'ASSIST_CHECK_PASSED'
+    #: The check failed (``outcome``: ``wrong_number``, ``not_me``, ``coached``, ``declined``): page someone.
+    ASSIST_CHECK_FAILED = 'ASSIST_CHECK_FAILED'
+    #: The help desk lifted the person's approval freeze after a check on the phone.
+    ASSIST_UNFROZEN = 'ASSIST_UNFROZEN'
+    #: The person checked that the agent from IT is really working on their account.
+    ASSIST_CLAIM_CONFIRMED = 'ASSIST_CLAIM_CONFIRMED'
+    #: Nobody from IT was working on the account: someone is pretending to be IT. No ``assistId``; page someone.
+    ASSIST_CLAIM_UNVERIFIED = 'ASSIST_CLAIM_UNVERIFIED'
+
+
+class ReplayCache:
+    """
+    Storage for webhook ``jti`` values already accepted. ``check_and_set``
+    must atomically record ``jti`` for ``ttl_seconds`` and return ``True`` if
+    it was NOT seen before. Subclass it (or duck-type it) over Redis / your
+    database when you run several processes.
+    """
+
+    def check_and_set(self, jti: str, ttl_seconds: int) -> bool:
+        raise NotImplementedError
+
+
+class MemoryReplayCache(ReplayCache):
+    """In-process :class:`ReplayCache`. Entries expire; the dict is capped. Thread-safe."""
+
+    def __init__(self, max_entries: int = 100_000):
+        self._seen: Dict[str, float] = {}
+        self._max = max_entries
+        self._lock = threading.Lock()
+
+    def check_and_set(self, jti: str, ttl_seconds: int) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            expires = self._seen.get(jti)
+            if expires is not None and expires > now:
+                return False
+            if len(self._seen) >= self._max:
+                for key in [k for k, exp in self._seen.items() if exp <= now]:
+                    del self._seen[key]
+                while len(self._seen) >= self._max:
+                    self._seen.pop(next(iter(self._seen)))
+            self._seen[jti] = now + ttl_seconds
+            return True
+
+
+def _canonicalize(payload: Dict[str, Any]) -> str:
+    """
+    Reproduce the server's ``stableStringify``:
+    drop the ``signature`` field, sort the TOP-LEVEL keys, and serialize
+    with no whitespace. Nested values keep their order, exactly as
+    ``JSON.stringify`` leaves them.
+    """
+    without_sig = {k: v for k, v in payload.items() if k != "signature"}
+    ordered = {k: without_sig[k] for k in sorted(without_sig)}
+    return json.dumps(ordered, separators=(",", ":"), ensure_ascii=False)
+
+
+def _parse_iso_timestamp(value: Any) -> Optional[float]:
+    if not isinstance(value, str):
+        return None
+    try:
+        text = value.replace("Z", "+00:00")
+        return datetime.fromisoformat(text).timestamp()
+    except ValueError:
+        return None
+
+
+class Webhook:
+    def __init__(self, config: Config):
+        self._config = config
+
+    def verify(
+        self,
+        raw_body: str,
+        signature: Optional[str] = None,
+        tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+        replay_cache: Optional[ReplayCache] = None,
+    ) -> Dict[str, Any]:
+        """
+        Verify the signature of an incoming TouchQue webhook and return the
+        decoded payload.
+
+        Args:
+            raw_body: The raw request body as text, exactly as received (do
+                not re-serialize it), e.g. Flask's
+                ``request.get_data(as_text=True)``.
+            signature: The ``x-signature`` header value. Optional — if omitted,
+                the ``signature`` field carried inside the body is used.
+            tolerance_seconds: Reject a callback whose signed ``timestamp`` is
+                missing, invalid or further than this from now (replay
+                protection). Pass ``0`` to disable the check.
+            replay_cache: Optional :class:`ReplayCache` (e.g. a shared
+                :class:`MemoryReplayCache`). A second delivery of the same
+                ``jti`` raises :class:`TouchQueWebhookReplayException`.
+
+        Raises:
+            TouchQueWebhookSignatureException: signature missing, malformed
+                body, signature mismatch, or a stale callback.
+            TouchQueWebhookReplayException: this ``jti`` was already accepted
+                (a subclass of the above, so existing handlers still reject it).
+        """
+        if not isinstance(raw_body, str):
+            raise TouchQueWebhookSignatureException("raw_body must be a string")
+
+        try:
+            payload = json.loads(raw_body)
+        except json.JSONDecodeError:
+            raise TouchQueWebhookSignatureException("Invalid JSON payload")
+        if not isinstance(payload, dict):
+            raise TouchQueWebhookSignatureException("Webhook payload must be a JSON object")
+
+        provided = signature or payload.get("signature")
+        if not isinstance(provided, str) or not provided:
+            raise TouchQueWebhookSignatureException("No signature provided")
+
+        mac = hmac.new(
+            self._config.api_secret.encode("utf-8"),
+            _canonicalize(payload).encode("utf-8"),
+            hashlib.sha256,
+        )
+        # Do NOT put the expected signature in the exception — a caller that
+        # surfaces the error text would hand an attacker a signing oracle.
+        # Compared as bytes: compare_digest raises TypeError for a str with non-ASCII text.
+        if not hmac.compare_digest(mac.hexdigest().encode("ascii"), provided.encode("utf-8")):
+            raise TouchQueWebhookSignatureException("Invalid webhook signature")
+
+        # TouchQue always signs a timestamp, so a missing or unparseable one
+        # fails closed instead of skipping the freshness check.
+        if tolerance_seconds and tolerance_seconds > 0:
+            ts = _parse_iso_timestamp(payload.get("timestamp"))
+            if ts is None:
+                raise TouchQueWebhookSignatureException("Webhook timestamp is missing or invalid")
+            if abs(time.time() - ts) > tolerance_seconds:
+                raise TouchQueWebhookSignatureException("Webhook timestamp is outside the allowed window")
+
+        if replay_cache is not None:
+            jti = payload.get("jti")
+            if not isinstance(jti, str) or not jti:
+                raise TouchQueWebhookSignatureException("Webhook jti is missing")
+            # Remember it for twice the window so it outlives any timestamp
+            # that could still pass the freshness check.
+            ttl = max((tolerance_seconds or 0) * 2, 600)
+            if not replay_cache.check_and_set(jti, ttl):
+                raise TouchQueWebhookReplayException(jti)
+
+        return payload

touchque/safe_guard.py

@@ -0,0 +1,308 @@
+"""Safe Guard approvals, checked without trusting TouchQue.
+
+The approver's phone decodes the raw Safe transaction itself and signs, with a P-256 key only
+its biometrics unlock, a 105-byte approval that TouchQueSafeGuard checks on chain::
+
+    index (1) | expiresAt (8) | displayDigest (32) | r (32) | s (32)
+
+over the SHA-256 of the 149-byte message::
+
+    "TQG1" | purpose (1) | chainId (32) | guard (20) | Safe (20) | subject (32) | expiresAt (8) | displayDigest (32)
+
+where subject is the Safe transaction hash (EIP-712, purpose 1 ``approve``) or, for a change the
+guard schedules, the governance hash (purpose 2 ``schedule``). ``verify_safe_approval`` makes the
+guard's check off chain: both hashes are computed here from the raw fields, so a co-signer (or
+your own server) refuses an approval of anything else, whoever relayed it.
+
+The hashes need nothing else; ``verify_safe_approval`` needs the optional ``cryptography``
+package: ``pip install "touchque-authenticator[proof]"``.
+"""
+import datetime
+import hashlib
+import re
+import time
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Union
+
+from .exceptions import TouchQueConfigException
+
+__all__ = [
+    'safe_tx_hash', 'safe_governance_hash', 'safe_approval_message', 'safe_display_digest', 'verify_safe_approval',
+    'with_safe_approvals', 'safe_schedule_call',
+]
+
+_MAGIC = b'TQG1'
+_PURPOSES = {'approve': 1, 'schedule': 2}
+# The guard (MAX_APPROVAL_TTL) refuses an approval valid for longer than a day.
+_MAX_APPROVAL_TTL = 86400
+# OpenZeppelin P256 (the guard) refuses s above N/2.
+_HALF_N = 0x7fffffff800000007fffffffffffffffde737d56d38bcf4279dce5617e3192a8
+_MAX_UINT256 = (1 << 256) - 1
+_MAX_UINT64 = (1 << 64) - 1
+_ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
+_ADDRESS = re.compile(r'^0x[0-9a-fA-F]{40}$')
+_HEX = re.compile(r'^0x(?:[0-9a-fA-F]{2})*$')
+_APPROVAL = re.compile(r'^(?:0x)?[0-9a-fA-F]{210}$')
+_KEY = re.compile(r'^[0-9a-fA-F]{128}$')
+
+# ── Keccak-256 (the Ethereum hash: Keccak padding, not SHA3-256) ──
+_RC = [int(h, 16) for h in (
+    '0000000000000001', '0000000000008082', '800000000000808a', '8000000080008000', '000000000000808b', '0000000080000001',
+    '8000000080008081', '8000000000008009', '000000000000008a', '0000000000000088', '0000000080008009', '000000008000000a',
+    '000000008000808b', '800000000000008b', '8000000000008089', '8000000000008003', '8000000000008002', '8000000000000080',
+    '000000000000800a', '800000008000000a', '8000000080008081', '8000000000008080', '0000000080000001', '8000000080008008',
+)]
+# Rotation of lane x + 5y.
+_ROT = (0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14)
+_MASK = (1 << 64) - 1
+
+
+def _rotl(v: int, n: int) -> int:
+    return ((v << n) | (v >> (64 - n))) & _MASK if n else v
+
+
+def _keccak_f(a: List[int]) -> List[int]:
+    for rc in _RC:
+        c = [a[x] ^ a[x + 5] ^ a[x + 10] ^ a[x + 15] ^ a[x + 20] for x in range(5)]
+        d = [c[(x + 4) % 5] ^ _rotl(c[(x + 1) % 5], 1) for x in range(5)]
+        a = [a[i] ^ d[i % 5] for i in range(25)]
+        b = [0] * 25
+        for x in range(5):
+            for y in range(5):
+                b[y + 5 * ((2 * x + 3 * y) % 5)] = _rotl(a[x + 5 * y], _ROT[x + 5 * y])
+        a = [b[i] ^ (~b[i - i % 5 + (i + 1) % 5] & b[i - i % 5 + (i + 2) % 5]) for i in range(25)]
+        a[0] ^= rc
+    return a
+
+
+def _keccak256(data: bytes) -> bytes:
+    rate = 136
+    padded = bytearray(data) + bytearray(rate - len(data) % rate)
+    padded[len(data)] ^= 0x01
+    padded[-1] ^= 0x80
+    a = [0] * 25
+    for off in range(0, len(padded), rate):
+        for k in range(rate // 8):
+            a[k] ^= int.from_bytes(padded[off + 8 * k:off + 8 * k + 8], 'little')
+        a = _keccak_f(a)
+    return b''.join(a[k].to_bytes(8, 'little') for k in range(4))
+
+
+_DOMAIN_TYPEHASH = _keccak256(b'EIP712Domain(uint256 chainId,address verifyingContract)')
+_SAFE_TX_TYPEHASH = _keccak256(
+    b'SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,'
+    b'address gasToken,address refundReceiver,uint256 nonce)')
+_GOVERNANCE_TYPEHASH = _keccak256(b'TouchQueGovernance(uint256 chainId,address safe,address to,uint256 value,bytes32 dataHash,uint8 operation)')
+_SCHEDULE_SELECTOR = _keccak256(b'schedule(address,bytes32,bytes)')[:4]
+
+
+# ── Field parsing: the partner's own data, so a wrong field raises ──
+def _uint(value: Any, field: str, top: int = _MAX_UINT256) -> int:
+    v = None
+    if isinstance(value, int) and not isinstance(value, bool):
+        v = value
+    elif isinstance(value, str) and re.match(r'^(0|[1-9][0-9]*)$', value):
+        v = int(value)
+    if v is None or v < 0 or v > top:
+        raise TouchQueConfigException(f'safe_guard: {field} must be a non-negative integer (a decimal string for large values).')
+    return v
+
+
+def _address(value: Any, field: str) -> bytes:
+    if not isinstance(value, str) or not _ADDRESS.match(value):
+        raise TouchQueConfigException(f'safe_guard: {field} must be an address (0x and 40 hex characters).')
+    return bytes.fromhex(value[2:])
+
+
+def _hex(value: Any, field: str, size: Optional[int] = None) -> bytes:
+    if not isinstance(value, str) or not _HEX.match(value) or (size is not None and len(value) != 2 + 2 * size):
+        raise TouchQueConfigException(f'safe_guard: {field} must be 0x-prefixed hex' + (f' of {size} bytes.' if size is not None else '.'))
+    return bytes.fromhex(value[2:])
+
+
+def _strip0x(s: str) -> str:
+    return s[2:] if s.startswith('0x') else s
+
+
+def _word(v: int) -> bytes:
+    return v.to_bytes(32, 'big')
+
+
+def _pad(b: bytes) -> bytes:
+    return bytes(32 - len(b)) + b
+
+
+def _target(target: Mapping[str, Any]) -> Dict[str, Any]:
+    tx = target.get('tx') if isinstance(target, Mapping) else None
+    if not isinstance(tx, Mapping):
+        raise TouchQueConfigException('safe_guard: pass {"chainId", "safe", "guard", "tx": {"to", "value", "data", "operation", ..., "nonce"}}.')
+    operation = tx.get('operation', 0)
+    if operation not in (0, 1) or isinstance(operation, bool):
+        raise TouchQueConfigException('safe_guard: tx.operation must be 0 (call) or 1 (delegatecall).')
+    return {
+        'chainId': _uint(target.get('chainId'), 'chainId', _MAX_UINT64),
+        'safe': _address(target.get('safe'), 'safe'),
+        'guard': _address(target.get('guard'), 'guard'),
+        'to': _address(tx.get('to'), 'tx.to'),
+        'value': _uint(tx.get('value', 0), 'tx.value'),
+        'data': _hex(tx.get('data', '0x'), 'tx.data'),
+        'operation': operation,
+        'safeTxGas': _uint(tx.get('safeTxGas', 0), 'tx.safeTxGas'),
+        'baseGas': _uint(tx.get('baseGas', 0), 'tx.baseGas'),
+        'gasPrice': _uint(tx.get('gasPrice', 0), 'tx.gasPrice'),
+        'gasToken': _address(tx.get('gasToken', _ZERO_ADDRESS), 'tx.gasToken'),
+        'refundReceiver': _address(tx.get('refundReceiver', _ZERO_ADDRESS), 'tx.refundReceiver'),
+        'nonce': _uint(tx.get('nonce'), 'tx.nonce'),
+    }
+
+
+def safe_tx_hash(target: Mapping[str, Any]) -> str:
+    """The Safe transaction hash (EIP-712, domain = chainId + the Safe): what the owners sign and an ordinary approval covers."""
+    t = _target(target)
+    domain = _keccak256(_DOMAIN_TYPEHASH + _word(t['chainId']) + _pad(t['safe']))
+    struct = _keccak256(
+        _SAFE_TX_TYPEHASH + _pad(t['to']) + _word(t['value']) + _keccak256(t['data']) + _word(t['operation'])
+        + _word(t['safeTxGas']) + _word(t['baseGas']) + _word(t['gasPrice']) + _pad(t['gasToken']) + _pad(t['refundReceiver'])
+        + _word(t['nonce']))
+    return '0x' + _keccak256(b'\x19\x01' + domain + struct).hex()
+
+
+def safe_governance_hash(target: Mapping[str, Any]) -> str:
+    """What the guard schedules a governance change under: the change itself, without the nonce or gas fields."""
+    t = _target(target)
+    return '0x' + _keccak256(
+        _GOVERNANCE_TYPEHASH + _word(t['chainId']) + _pad(t['safe']) + _pad(t['to']) + _word(t['value'])
+        + _keccak256(t['data']) + _word(t['operation'])).hex()
+
+
+def safe_approval_message(purpose: str, chain_id: Union[int, str], guard: str, safe: str, subject: str,
+                          expires_at: Union[int, str], display_digest: str) -> str:
+    """The 149-byte message the phone signs (its SHA-256 is what the guard verifies), as 0x hex."""
+    if purpose not in _PURPOSES:
+        raise TouchQueConfigException("safe_guard: purpose is 'approve' or 'schedule'.")
+    return '0x' + (
+        _MAGIC + bytes([_PURPOSES[purpose]]) + _word(_uint(chain_id, 'chainId', _MAX_UINT64)) + _address(guard, 'guard')
+        + _address(safe, 'safe') + _hex(subject, 'subject', 32) + _uint(expires_at, 'expiresAt', _MAX_UINT64).to_bytes(8, 'big')
+        + _hex(display_digest, 'displayDigest', 32)).hex()
+
+
+def safe_display_digest(rows: Iterable[Mapping[str, str]]) -> str:
+    """SHA-256 of the rows as "label\\x1Fvalue" joined by "\\x1E" (UTF-8), as 0x hex: the digest an approval carries."""
+    canonical = '\x1e'.join(f"{r['label']}\x1f{r['value']}" for r in rows)
+    return '0x' + hashlib.sha256(canonical.encode('utf-8')).hexdigest()
+
+
+def _public_key(key: Union[str, Mapping[str, str]]):
+    if isinstance(key, Mapping):
+        xy = _strip0x(str(key.get('x', ''))) + _strip0x(str(key.get('y', '')))
+    else:
+        xy = _strip0x(str(key))
+    if not _KEY.match(xy):
+        return None
+    try:
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except ImportError as e:  # pragma: no cover - depends on the environment
+        raise TouchQueConfigException('Safe Guard approvals need the cryptography package: pip install "touchque-authenticator[proof]"') from e
+    try:
+        return ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), b'\x04' + bytes.fromhex(xy))
+    except ValueError:
+        return None
+
+
+def _seconds(now: Union[None, int, float, datetime.datetime]) -> int:
+    if now is None:
+        return int(time.time())
+    if isinstance(now, datetime.datetime):
+        return int(now.timestamp())
+    return int(now)
+
+
+def verify_safe_approval(target: Mapping[str, Any], approval: str, public_key: Union[str, Mapping[str, str]], *,
+                         purpose: Optional[str] = None, approver_index: Optional[int] = None,
+                         display_digest: Optional[str] = None, rows: Optional[Iterable[Mapping[str, str]]] = None,
+                         now: Union[None, int, float, datetime.datetime] = None) -> Dict[str, Any]:
+    """Checks a phone's Safe Guard approval the way TouchQueSafeGuard does, without trusting the server that relayed it.
+
+    The Safe and governance hashes come from ``target`` (``{"chainId", "safe", "guard", "tx"}``),
+    the key from the guard's approver list on chain (``x || y``, 128 hex characters, or
+    ``{"x", "y"}``). ``purpose`` (``approve`` or ``schedule``): the one you expect; without it,
+    only ``approve`` (this exact transaction, to execute) is accepted, so name ``schedule`` to
+    check an approval that schedules a governance change. ``approver_index``: the approval
+    must name it. ``display_digest`` or ``rows``: from your own decoding, the rows the phone must
+    have shown. ``now``: a datetime or Unix seconds.
+
+    Returns ``{"valid", "reason", "purpose", "approverIndex", "expiresAt", "displayDigest",
+    "safeTxHash", "governanceHash"}``; ``reason`` is ``None`` when valid, else one of
+    ``approval_malformed``, ``public_key_invalid``, ``approver_index_mismatch``,
+    ``approval_expired``, ``rows_differ``, ``high_s``, ``signature_invalid``. Raises only when
+    ``target`` is not a Safe transaction::
+
+        status = tq.safe_guard.status(request_id)
+        check = verify_safe_approval(my_tx, status['safeTx']['approval'], approver_key_from_chain, approver_index=0)
+        if not check['valid']:
+            raise RuntimeError(f"approval refused: {check['reason']}")
+    """
+    t = _target(target)
+    hashes = {'safeTxHash': safe_tx_hash(target), 'governanceHash': safe_governance_hash(target)}
+    parsed: Dict[str, Any] = {'approverIndex': None, 'expiresAt': None, 'displayDigest': None}
+
+    def refuse(reason: str) -> Dict[str, Any]:
+        return {'valid': False, 'reason': reason, 'purpose': None, **parsed, **hashes}
+
+    if not isinstance(approval, str) or not _APPROVAL.match(approval):
+        return refuse('approval_malformed')
+    b = bytes.fromhex(_strip0x(approval))
+    expires_at = int.from_bytes(b[1:9], 'big')
+    parsed = {'approverIndex': b[0], 'expiresAt': expires_at, 'displayDigest': '0x' + b[9:41].hex()}
+    key = _public_key(public_key)
+    if key is None:
+        return refuse('public_key_invalid')
+    if approver_index is not None and approver_index != b[0]:
+        return refuse('approver_index_mismatch')
+    seconds = _seconds(now)
+    if expires_at < seconds or expires_at > seconds + _MAX_APPROVAL_TTL:
+        return refuse('approval_expired')
+    expected = display_digest if display_digest is not None else (safe_display_digest(rows) if rows is not None else None)
+    if expected is not None and '0x' + _strip0x(expected.lower()) != parsed['displayDigest']:
+        return refuse('rows_differ')
+    s = int.from_bytes(b[73:105], 'big')
+    if s > _HALF_N:
+        return refuse('high_s')
+
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes as crypto_hashes
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+    signature = encode_dss_signature(int.from_bytes(b[41:73], 'big'), s)
+    # Never both: a schedule approval (no nonce, no gas fields) must not pass as one to execute.
+    p = purpose or 'approve'
+    message = safe_approval_message(
+        p, t['chainId'], '0x' + t['guard'].hex(), '0x' + t['safe'].hex(),
+        hashes['safeTxHash'] if p == 'approve' else hashes['governanceHash'], expires_at, parsed['displayDigest'])
+    try:
+        key.verify(signature, bytes.fromhex(message[2:]), ec.ECDSA(crypto_hashes.SHA256()))
+    except InvalidSignature:
+        return refuse('signature_invalid')
+    return {'valid': True, 'reason': None, 'purpose': p, **parsed, **hashes}
+
+
+def _approvals(approvals: Iterable[str]) -> List[bytes]:
+    items = list(approvals)
+    if not 1 <= len(items) <= 255:
+        raise TouchQueConfigException('safe_guard: pass 1 to 255 approvals.')
+    out = [_hex(a if isinstance(a, str) and a.startswith('0x') else f'0x{a}', f'approvals[{i}]', 105) for i, a in enumerate(items)]
+    return sorted(out, key=lambda a: a[0])
+
+
+def with_safe_approvals(owner_signatures: str, approvals: Iterable[str]) -> str:
+    """The owners' Safe signatures with the approvals appended (approvals by index | count | "TQG1"):
+    the ``signatures`` argument of ``execTransaction`` for an ordinary transaction."""
+    items = _approvals(approvals)
+    return '0x' + (_hex(owner_signatures, 'ownerSignatures') + b''.join(items) + bytes([len(items)]) + _MAGIC).hex()
+
+
+def safe_schedule_call(safe: str, governance_hash: str, approvals: Iterable[str]) -> str:
+    """The call data of ``guard.schedule(safe, governanceHash, approvals)``, which starts a governance change's waiting time."""
+    joined = b''.join(_approvals(approvals))
+    return '0x' + (
+        _SCHEDULE_SELECTOR + _pad(_address(safe, 'safe')) + _hex(governance_hash, 'governanceHash', 32) + _word(96)
+        + _word(len(joined)) + joined + bytes(-len(joined) % 32)).hex()