touchque-authenticator 4.2.0__py3-none-any.whl

touchque/security_events.py

@@ -0,0 +1,205 @@
+"""Shared Signals (OpenID Shared Signals Framework 1.0): Security Event Tokens.
+
+An identity provider sends a SET (RFC 8417) when something happens to a
+person's account after sign-in: CAEP session-revoked, credential-change,
+device-compliance-change; RISC account-disabled, credential-compromise.
+TouchQue SSO sends them for an organization's members to the receivers its
+admin adds (Organization > Continuous access). Your app ends the person's
+sessions or asks them to sign in again.
+
+Push delivery (RFC 8935), the SET is the request body (application/secevent+jwt)::
+
+    verifier = SecurityEventVerifier(issuer='https://sso.touchque.com', audience='https://app.example.com')
+
+    @app.post('/ssf')
+    def ssf():
+        try:
+            event = verifier.verify(request.get_data(as_text=True))
+        except SecurityEventError as e:
+            return {'err': e.code, 'description': str(e)}, 400
+        if event.name == 'session-revoked':
+            end_sessions_of(event.subject.get('email'))
+        return '', 202
+
+Poll delivery (RFC 8936): ``poll_security_events(url=..., token=..., ack=[...])``.
+
+A SET does not expire: it says what happened. Keep the jtis you handled and
+skip a repeat. Needs the optional ``cryptography`` package:
+``pip install "touchque-authenticator[agent]"``.
+"""
+
+import re
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .exceptions import TouchQueConfigException
+from .mcp_auth import _json_part, _b64d, _public_key, _verify
+from .cross_app_access import _get_json, _safe_url
+
+SET_TYP = 'secevent+jwt'
+_NAMESPACE = re.compile(r'^https://schemas\.openid\.net/secevent/(caep|risc|ssf)/event-type/([a-z0-9-]+)$')
+
+#: The event types TouchQue sends, by their short name.
+SECURITY_EVENT_TYPES = {
+    'session-revoked': 'https://schemas.openid.net/secevent/caep/event-type/session-revoked',
+    'credential-change': 'https://schemas.openid.net/secevent/caep/event-type/credential-change',
+    'device-compliance-change': 'https://schemas.openid.net/secevent/caep/event-type/device-compliance-change',
+    'account-disabled': 'https://schemas.openid.net/secevent/risc/event-type/account-disabled',
+    'credential-compromise': 'https://schemas.openid.net/secevent/risc/event-type/credential-compromise',
+    'verification': 'https://schemas.openid.net/secevent/ssf/event-type/verification',
+    'stream-updated': 'https://schemas.openid.net/secevent/ssf/event-type/stream-updated',
+}
+
+
+class SecurityEventError(Exception):
+    """A refused SET. ``code`` is the RFC 8935 error to answer with (HTTP 400 ``{"err": code}``):
+    invalid_request, invalid_key, invalid_issuer or invalid_audience; temporarily_unavailable
+    when the issuer's keys could not be read (answer 503: the transmitter tries again)."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass
+class SecurityEvent:
+    jti: str
+    issuer: str
+    audience: List[str]
+    #: Seconds since the epoch.
+    issued_at: int
+    #: TouchQue puts the case code of its decision here ("Why?" in the dashboard).
+    txn: Optional[str]
+    #: The subject as sent (sub_id): {'format': 'email', 'email': ...} for a person.
+    subject: Dict[str, Any]
+    #: The event type URI.
+    type: str
+    #: Its short name (session-revoked ...) for CAEP, RISC and SSF types; None for others.
+    name: Optional[str]
+    #: The event's own claims (event_timestamp, reason_admin, credential_type ...).
+    claims: Dict[str, Any]
+
+
+class SecurityEventVerifier:
+    """Checks a SET: signature (RS256, the issuer's keys), typ, issuer, audience, one event."""
+
+    def __init__(self, issuer: str, audience: str, jwks_uri: Optional[str] = None, jwks: Optional[Dict[str, Any]] = None,
+                 clock_skew: int = 300):
+        if not issuer or not audience:
+            raise TouchQueConfigException("SecurityEventVerifier needs issuer (the transmitter) and audience (your stream's aud)")
+        self.issuer = issuer
+        self.audience = audience
+        self.jwks_uri = jwks_uri
+        self.skew = clock_skew
+        self._pinned = jwks is not None
+        self._keys: Dict[str, Any] = {}
+        self._keys_at = 0.0
+        self._tried_at = 0.0
+        self._lock = threading.Lock()
+        if jwks is not None:
+            self._set_keys(jwks)
+
+    def _set_keys(self, jwks: Dict[str, Any]) -> None:
+        self._keys = {k['kid']: _public_key(k) for k in jwks.get('keys', []) if k.get('kid')}
+        self._keys_at = time.time()
+
+    def _load_keys(self) -> None:
+        if not self.jwks_uri:
+            meta = _get_json(self.issuer.rstrip('/') + '/.well-known/ssf-configuration')
+            if meta.get('issuer') != self.issuer or not isinstance(meta.get('jwks_uri'), str):
+                raise RuntimeError("the transmitter's metadata does not match its issuer")
+            self.jwks_uri = meta['jwks_uri']
+        if not _safe_url(self.jwks_uri):
+            raise RuntimeError(f'{self.jwks_uri} must be an https URL')
+        self._set_keys(_get_json(self.jwks_uri))
+
+    def _key_for(self, kid: str):
+        if self._pinned:
+            return self._keys.get(kid)
+        with self._lock:
+            if not self._keys_at or time.time() - self._keys_at > 3600:
+                self._load_keys()
+            if kid not in self._keys and time.time() - self._tried_at > 300:
+                self._tried_at = time.time()
+                self._load_keys()
+            return self._keys.get(kid)
+
+    def verify(self, token: str) -> SecurityEvent:
+        parts = token.strip().split('.') if isinstance(token, str) else []
+        if len(parts) != 3:
+            raise SecurityEventError('invalid_request', 'not a JWT')
+        try:
+            head = _json_part(parts[0])
+            c = _json_part(parts[1])
+        except Exception:
+            raise SecurityEventError('invalid_request', 'not a JWT')
+        if str(head.get('typ') or '').lower() != SET_TYP:
+            raise SecurityEventError('invalid_request', 'not a Security Event Token (typ secevent+jwt)')
+        if head.get('alg') != 'RS256' or not isinstance(head.get('kid'), str):
+            raise SecurityEventError('invalid_key', 'unsupported signature')
+        try:
+            key = self._key_for(head['kid'])
+        except Exception as e:
+            raise SecurityEventError('temporarily_unavailable', f"the transmitter's keys could not be read: {e}")
+        try:
+            sig = _b64d(parts[2])
+        except Exception:
+            raise SecurityEventError('invalid_key', 'signature does not verify')
+        if key is None or not _verify(f'{parts[0]}.{parts[1]}'.encode('ascii'), sig, 'RS256', key):
+            raise SecurityEventError('invalid_key', 'signature does not verify')
+        if c.get('iss') != self.issuer:
+            raise SecurityEventError('invalid_issuer', 'another issuer')
+        aud = c.get('aud')
+        audience = [a for a in (aud if isinstance(aud, list) else [aud]) if isinstance(a, str)]
+        if self.audience not in audience:
+            raise SecurityEventError('invalid_audience', 'not for this receiver')
+        iat = c.get('iat')
+        if not isinstance(c.get('jti'), str) or not isinstance(iat, int) or isinstance(iat, bool):
+            raise SecurityEventError('invalid_request', 'jti and iat are required')
+        if iat - self.skew > int(time.time()):
+            raise SecurityEventError('invalid_request', 'issued in the future')
+        events = c.get('events')
+        if not isinstance(events, dict) or len(events) != 1:
+            raise SecurityEventError('invalid_request', 'a SET carries exactly one event')
+        (type_, claims), = events.items()
+        m = _NAMESPACE.match(type_)
+        sub = c.get('sub_id')
+        return SecurityEvent(
+            jti=c['jti'], issuer=c['iss'], audience=audience, issued_at=iat, txn=c['txn'] if isinstance(c.get('txn'), str) else None,
+            subject=sub if isinstance(sub, dict) else {}, type=type_, name=m.group(2) if m else None,
+            claims=claims if isinstance(claims, dict) else {},
+        )
+
+
+def poll_security_events(*, url: str, token: str, ack: Optional[List[str]] = None,
+                         set_errs: Optional[Dict[str, Dict[str, str]]] = None, max_events: Optional[int] = None,
+                         return_immediately: Optional[bool] = None) -> Dict[str, Any]:
+    """One poll (RFC 8936): acknowledges what you handled and returns
+    ``{'sets': {jti: token}, 'more_available': bool}``."""
+    if not _safe_url(url):
+        raise TouchQueConfigException(f'{url} must be an https URL')
+    if not token:
+        raise TouchQueConfigException("poll_security_events needs the stream's token")
+    body: Dict[str, Any] = {}
+    if ack is not None:
+        body['ack'] = ack
+    if set_errs is not None:
+        body['setErrs'] = set_errs
+    if max_events is not None:
+        body['maxEvents'] = max_events
+    if return_immediately is not None:
+        body['returnImmediately'] = return_immediately
+    r = requests.post(url, json=body, timeout=30, allow_redirects=False,
+                      headers={'Accept': 'application/json', 'Authorization': f'Bearer {token}'})
+    try:
+        data = r.json()
+    except ValueError:
+        data = {}
+    if r.status_code != 200:
+        raise SecurityEventError(str(data.get('error') or 'server_error'), f'{url} answered {r.status_code}')
+    sets = data.get('sets')
+    return {'sets': sets if isinstance(sets, dict) else {}, 'more_available': data.get('moreAvailable') is True}

touchque/steps.py

@@ -0,0 +1,239 @@
+"""
+The headless step-up flow shared by every integration (Django, FastAPI,
+Flask, or your own framework): start -> show the step in YOUR UI -> check ->
+complete exactly once.
+
+A "step" is plain JSON-serializable data: what state the approval is in and
+whatever the user has to see (the matching number, the enrollment QR code,
+the offline QR code). It never contains API secrets.
+"""
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from .exceptions import TouchQueAPIException, TouchQueConfigException, TouchQueException
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .client import TouchQue
+
+LoginDetails = Union[Dict[str, Any], List[Dict[str, Any]]]
+
+# States: waiting | approved | rejected | expired | enroll | passkey_required
+#         | offline | blocked | frozen | rate_limited
+
+
+def normalize_details(details: Optional[LoginDetails]) -> List[Dict[str, str]]:
+    """Same normalization the API does: a dict or a list of {label, value} -> [{label, value}] strings."""
+    if not details:
+        return []
+    if isinstance(details, list):
+        pairs = [(d['label'], d['value']) for d in details]
+    else:
+        pairs = list(details.items())
+    return [{'label': str(label).strip(), 'value': str(value).strip()} for label, value in pairs]
+
+
+def details_digest(details: Optional[LoginDetails]) -> str:
+    pairs = normalize_details(details)
+    if not pairs:
+        return ''
+    canonical = '\x1e'.join(f"{p['label']}\x1f{p['value']}" for p in pairs)
+    return hashlib.sha256(canonical.encode('utf-8')).hexdigest()
+
+
+def _err_code(err: TouchQueAPIException) -> Optional[str]:
+    return err.code or (err.data or {}).get('error')
+
+
+def _why(res: Dict[str, Any]) -> Dict[str, Any]:
+    """"Why?": the case code (``K7P-2QX``) and plain reasons of a login request's
+    answer, for its step. Both are safe for the browser: show the code with the
+    step ("Tell your support team: K7P-2QX")."""
+    out: Dict[str, Any] = {}
+    if isinstance(res.get('caseCode'), str) and res['caseCode']:
+        out['caseCode'] = res['caseCode']
+    reasons = [{'code': r['code'], 'text': r.get('text') if isinstance(r.get('text'), str) else ''}
+               for r in (res.get('reasons') or []) if isinstance(r, dict) and isinstance(r.get('code'), str)]
+    if reasons:
+        out['reasons'] = reasons
+    return out
+
+
+def start(client: 'TouchQue', action: str, user: str, details: Optional[LoginDetails] = None,
+          reference_id: Optional[str] = None, ip: Optional[str] = None, user_agent: Optional[str] = None,
+          enroll: bool = True, browser_proof: Optional[str] = None,
+          context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Starts an approval for `action` — never waits.
+
+    ``browser_proof`` (silent sign-ins): the browser's device-bound key proof
+    (``X-TouchQue-Browser``), passed through untouched. Once the user
+    approves, TouchQue knows this browser."""
+    if not user:
+        raise TouchQueConfigException('start() needs the user id')
+    norm = normalize_details(details)
+    try:
+        res = client.login.request(
+            user, type=action, reference_id=reference_id, client_ip=ip, user_agent=user_agent,
+            details=norm or None, browser_proof=browser_proof, context=context,
+        )
+        canary = res.get('canary')
+        canary = {'url': canary['url']} if isinstance(canary, dict) and isinstance(canary.get('url'), str) else None
+        if res.get('requiresPasskey'):
+            step = {'state': 'passkey_required', 'requestId': res.get('requestId'),
+                    'expiresAt': res.get('expiresAt'), 'details': norm or None, **_why(res)}
+            if canary:
+                step['canary'] = canary
+            return step
+        step = {
+            'state': 'waiting', 'requestId': res.get('requestId'), 'number': res.get('challengeCode'),
+            'expiresAt': res.get('expiresAt'), 'details': norm or None, **_why(res),
+        }
+        if res.get('telemetryToken'):
+            # Only when the workspace collects behavioural signals: lets the browser post
+            # them for this one request (@touchque/web does it when given `telemetry`).
+            step['telemetryToken'] = res['telemetryToken']
+        if canary:
+            # Mirror Alarm: the page showing this step loads the canary (@touchque/web does it), so
+            # a phishing proxy in front of your site gets the approval refused. Only on this first step.
+            step['canary'] = canary
+        return step
+    except TouchQueAPIException as err:
+        code = _err_code(err)
+        why = {'caseCode': err.case_code} if err.case_code else {}
+        if err.status == 404 and (code == 'device_not_linked' or 'linked device' in str(err).lower()):
+            if not enroll:
+                return {'state': 'enroll'}
+            return _enroll_step(client, user)
+        if err.status == 423:
+            return {'state': 'frozen', 'retryAfter': err.retry_after, **why}
+        if err.status == 429:
+            return {'state': 'rate_limited', 'retryAfter': err.retry_after, **why}
+        if err.status == 400 and (code == 'unknown_action' or 'invalid action type' in str(err).lower()):
+            raise TouchQueConfigException(
+                f'Unknown action "{action}". Create it once with client.action_types.define("{action}") '
+                'or in the Dashboard (Action Types).'
+            ) from err
+        if err.status == 403:
+            reason = (err.reason if code == 'blocked' else None) \
+                or ('passkey_not_registered' if code in ('passkey_not_registered',) or (err.data or {}).get('error') == 'phishing_resistant_required' else None) \
+                or ('action_disabled' if code == 'action_disabled' else None) \
+                or code or 'blocked'
+            return {'state': 'blocked', 'reason': reason, **why}
+        raise
+
+
+def _enroll_step(client: 'TouchQue', user: str) -> Dict[str, Any]:
+    """First-time linking. Never unlinks a phone: a secret is only re-issued
+    when the account is confirmed NOT linked."""
+    try:
+        gen = client.auth.generate_secret(user)
+        return {'state': 'enroll', 'enroll': {
+            'qrCodeDataUrl': gen.get('qrCodeDataUrl'), 'recoveryCodes': gen.get('recoveryCodes'),
+            'expiresAt': gen.get('expiresAt'),
+        }}
+    except TouchQueAPIException as err:
+        if err.status != 409:
+            raise
+        try:
+            current = client.auth.get_user(user)
+        except TouchQueAPIException:
+            current = None
+        if current and (current.get('used') or current.get('deviceId')):
+            return {'state': 'enroll', 'reason': 'already_linked'}
+        reset = client.auth.reset_secret(user)
+        return {'state': 'enroll', 'enroll': {
+            'qrCodeDataUrl': reset.get('qrCodeDataUrl'), 'recoveryCodes': reset.get('recoveryCodes'),
+            'expiresAt': reset.get('expiresAt'),
+        }}
+
+
+_STATE_MAP = {'PENDING': 'waiting', 'CONFIRMED': 'approved', 'REJECTED': 'rejected', 'EXPIRED': 'expired'}
+
+
+def check(client: 'TouchQue', request_id: str) -> Dict[str, Any]:
+    """Current state of a started approval."""
+    s = client.login.status(request_id)
+    state = 'passkey_required' if s.get('status') == 'PENDING' and s.get('requiresPasskey') \
+        else _STATE_MAP.get(s.get('status'), 'waiting')
+    step: Dict[str, Any] = {'state': state, 'requestId': request_id}
+    if state == 'approved' and s.get('assurance'):
+        step['assurance'] = s['assurance']
+    return step
+
+
+def complete(client: 'TouchQue', 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 and checks it is for THIS user,
+    action and transaction. Raises TouchQueException if it was already used,
+    not approved, or approved for something else."""
+    res = client.login.consume(request_id)
+    same_user = str(res.get('externalUsername', '')).lower() == str(user).lower()
+    same_details = details_digest(details) == details_digest(res.get('details') or [])
+    same_ref = (res.get('referenceId') or None) == (reference_id or None)
+    if not same_user or res.get('type') != action or not same_details or not same_ref:
+        raise TouchQueException('TouchQue: this approval is for a different user, action or transaction.')
+    approval = {
+        'requestId': request_id,
+        'user': res.get('externalUsername'),
+        'action': res.get('type'),
+        'assurance': res.get('assurance'),
+        'confirmedVia': res.get('confirmedVia'),
+        'approvalProof': res.get('approvalProof'),
+    }
+    if 'provisional' in res:
+        # Vishing Shield: approved during a call. Let the user in, but treat the session as limited:
+        # critical actions are refused until APPROVAL_RECONFIRMED, and APPROVAL_REVOKED means end it.
+        approval.update({
+            'provisional': bool(res.get('provisional')), 'revoked': bool(res.get('revoked')),
+            'revokeReason': res.get('revokeReason'), 'reconfirmedAt': res.get('reconfirmedAt'),
+        })
+    return approval
+
+
+# ── Guard token ──────────────────────────────────────────────────────────
+# The browser echoes this back while it waits. It is signed with a key derived
+# from the API secret and binds the approval to one user, action and
+# transaction, so it cannot be replayed for another user, amount or route.
+
+def _token_key(api_secret: str) -> bytes:
+    return hmac.new(api_secret.encode('utf-8'), b'touchque-guard-token-v1', hashlib.sha256).digest()
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')
+
+
+def _from_b64u(s: str) -> bytes:
+    pad = '=' * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def sign_guard_token(api_secret: str, claims: Dict[str, Any]) -> str:
+    body = _b64u(json.dumps(claims, separators=(',', ':')).encode('utf-8'))
+    mac = _b64u(hmac.new(_token_key(api_secret), body.encode('ascii'), hashlib.sha256).digest())
+    return f"v1.{body}.{mac}"
+
+
+def verify_guard_token(api_secret: str, token: Optional[str]) -> Optional[Dict[str, Any]]:
+    if not isinstance(token, str) or len(token) > 4096:
+        return None
+    parts = token.split('.')
+    if len(parts) != 3 or parts[0] != 'v1':
+        return None
+    _, body, mac = parts
+    # A header may carry any latin-1 text; only an ASCII token can be one we signed.
+    if not body.isascii() or not mac.isascii():
+        return None
+    expected = _b64u(hmac.new(_token_key(api_secret), body.encode('ascii'), hashlib.sha256).digest())
+    if not hmac.compare_digest(expected, mac):
+        return None
+    try:
+        claims = json.loads(_from_b64u(body))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if not isinstance(claims.get('exp'), (int, float)) or claims['exp'] < time.time() * 1000:
+        return None
+    return claims