touchque-authenticator 4.2.0__py3-none-any.whl

touchque/mcp_auth.py

@@ -0,0 +1,256 @@
+"""For an MCP server whose authorization server is TouchQue SSO (Organization
+→ MCP servers in the dashboard; issuer https://sso.touchque.com/mcp):
+
+- ``protected_resource_metadata()`` is its RFC 9728 document, served at the
+  paths ``metadata_paths()`` gives, so MCP clients find TouchQue and ask for a
+  token for exactly this server;
+- ``verify(method, url, headers)`` checks a request's token: signed by
+  TouchQue (its JWKS), this issuer, audience = this server's URL (RFC 8707),
+  not expired, and for a DPoP-bound token a fresh proof for this request;
+  ``McpAuthError`` carries the status (401, 403) and the WWW-Authenticate
+  header to send;
+- ``require_tool(claims, tool)`` raises 403 insufficient_scope naming the
+  scope a tool needs, so the client asks the member for more;
+- ``verify_token(token)`` checks a bearer token alone (FastMCP's
+  TokenVerifier gets only the token).
+
+    auth = McpAuth(issuer='https://sso.touchque.com/mcp', resource='https://mcp.acme.com/mcp',
+                   tools={'search_tickets': 'tickets:read', 'delete_ticket': 'tickets:delete'})
+
+Needs the optional ``cryptography`` package: ``pip install "touchque-authenticator[agent]"``.
+"""
+import base64
+import hashlib
+import json
+import threading
+import time
+from typing import Any, Dict, List, Mapping, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .exceptions import TouchQueConfigException
+
+__all__ = ['McpAuth', 'McpAuthError']
+
+
+def _b64d(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + '=' * (-len(text) % 4))
+
+
+def _b64e(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')
+
+
+def _json_part(part: str) -> Dict[str, Any]:
+    value = json.loads(_b64d(part))
+    if not isinstance(value, dict):
+        raise ValueError('not an object')
+    return value
+
+
+class McpAuthError(Exception):
+    """A refused request: send ``status`` with the ``www_authenticate`` header."""
+
+    def __init__(self, status: int, code: str, message: str, www_authenticate: str):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.www_authenticate = www_authenticate
+
+
+def _public_key(jwk: Mapping[str, Any]):
+    from cryptography.hazmat.primitives.asymmetric import ec, ed25519, rsa
+    if jwk.get('kty') == 'RSA':
+        return rsa.RSAPublicNumbers(int.from_bytes(_b64d(jwk['e']), 'big'), int.from_bytes(_b64d(jwk['n']), 'big')).public_key()
+    if jwk.get('kty') == 'EC' and jwk.get('crv') == 'P-256':
+        return ec.EllipticCurvePublicNumbers(int.from_bytes(_b64d(jwk['x']), 'big'), int.from_bytes(_b64d(jwk['y']), 'big'), ec.SECP256R1()).public_key()
+    if jwk.get('kty') == 'OKP' and jwk.get('crv') == 'Ed25519':
+        return ed25519.Ed25519PublicKey.from_public_bytes(_b64d(jwk['x']))
+    raise ValueError('unsupported key')
+
+
+def _verify(signing_input: bytes, sig: bytes, alg: str, key) -> bool:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import ec, padding
+    from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+    try:
+        if alg == 'RS256':
+            key.verify(sig, signing_input, padding.PKCS1v15(), hashes.SHA256())
+        elif alg == 'ES256':
+            if len(sig) != 64:
+                return False
+            key.verify(encode_dss_signature(int.from_bytes(sig[:32], 'big'), int.from_bytes(sig[32:], 'big')), signing_input, ec.ECDSA(hashes.SHA256()))
+        elif alg == 'EdDSA':
+            key.verify(sig, signing_input)
+        else:
+            return False
+        return True
+    except (InvalidSignature, ValueError, TypeError):
+        return False
+
+
+def _thumbprint(jwk: Mapping[str, Any]) -> str:
+    if jwk.get('kty') == 'EC':
+        members = {'crv': jwk['crv'], 'kty': 'EC', 'x': jwk['x'], 'y': jwk['y']}
+    elif jwk.get('kty') == 'RSA':
+        members = {'e': jwk['e'], 'kty': 'RSA', 'n': jwk['n']}
+    else:
+        members = {'crv': jwk['crv'], 'kty': jwk['kty'], 'x': jwk['x']}
+    return _b64e(hashlib.sha256(json.dumps(members, separators=(',', ':')).encode()).digest())
+
+
+class McpAuth:
+    """See the module docstring."""
+
+    def __init__(self, issuer: str, resource: str, tools: Optional[Dict[str, str]] = None,
+                 resource_name: Optional[str] = None, clock_skew: int = 60):
+        if not issuer or not resource:
+            raise TouchQueConfigException("McpAuth needs issuer (TouchQue SSO's MCP issuer) and resource (this server's URL)")
+        self.issuer = issuer.rstrip('/')
+        self.resource = resource
+        self.tools = dict(tools or {})
+        self.resource_name = resource_name
+        self.skew = clock_skew
+        self._keys: Dict[str, Any] = {}
+        self._keys_at = 0.0
+        self._tried_at = 0.0
+        self._proofs: Dict[str, float] = {}
+        self._lock = threading.Lock()
+
+    def metadata_paths(self) -> List[str]:
+        path = urlparse(self.resource).path.rstrip('/')
+        return ['/.well-known/oauth-protected-resource'] + ([f'/.well-known/oauth-protected-resource{path}'] if path else [])
+
+    def metadata_url(self) -> str:
+        u = urlparse(self.resource)
+        return f'{u.scheme}://{u.netloc}{self.metadata_paths()[-1]}'
+
+    def protected_resource_metadata(self) -> Dict[str, Any]:
+        doc: Dict[str, Any] = {
+            'resource': self.resource, 'authorization_servers': [self.issuer], 'bearer_methods_supported': ['header'],
+            'scopes_supported': list(dict.fromkeys(self.tools.values())), 'dpop_signing_alg_values_supported': ['ES256', 'EdDSA'],
+        }
+        if self.resource_name:
+            doc['resource_name'] = self.resource_name
+        return doc
+
+    def _fail(self, status: int, code: str, message: str, scope: Optional[str] = None) -> McpAuthError:
+        parts = [f'resource_metadata="{self.metadata_url()}"']
+        if code != 'missing_token':
+            parts.append(f'error="{code}"')
+            parts.append('error_description="{}"'.format(message.replace('"', "'")))
+            if scope:
+                parts.append(f'scope="{scope}"')
+        return McpAuthError(status, code, message, 'Bearer ' + ', '.join(parts))
+
+    def _load_keys(self) -> None:
+        u = urlparse(self.issuer)
+        meta = requests.get(f'{u.scheme}://{u.netloc}/.well-known/oauth-authorization-server{u.path.rstrip("/")}', timeout=5).json()
+        if str(meta.get('issuer', '')).rstrip('/') != self.issuer or not meta.get('jwks_uri'):
+            raise ValueError('the authorization server metadata does not match the issuer')
+        jwks = requests.get(meta['jwks_uri'], timeout=5).json()
+        self._keys = {k['kid']: _public_key(k) for k in jwks.get('keys', []) if k.get('kid')}
+        self._keys_at = time.time()
+
+    def _key_for(self, kid: str):
+        with self._lock:
+            if not self._keys_at or time.time() - self._keys_at > 600:
+                self._load_keys()
+            if kid not in self._keys and time.time() - self._tried_at > 60:
+                self._tried_at = time.time()
+                self._load_keys()
+            return self._keys.get(kid)
+
+    def _claims(self, token: str) -> Dict[str, Any]:
+        try:
+            h, p, s = token.split('.')
+            head, claims, sig = _json_part(h), _json_part(p), _b64d(s)
+        except ValueError:
+            raise self._fail(401, 'invalid_token', 'The token is malformed')
+        if head.get('typ') != 'at+jwt' or head.get('alg') not in ('RS256', 'ES256'):
+            raise self._fail(401, 'invalid_token', 'Not a TouchQue access token')
+        try:
+            key = self._key_for(str(head.get('kid', '')))
+        except Exception:
+            raise self._fail(401, 'invalid_token', "The authorization server's keys could not be read")
+        if key is None or not _verify(f'{h}.{p}'.encode('ascii'), sig, head['alg'], key):
+            raise self._fail(401, 'invalid_token', 'The token signature does not verify')
+        if str(claims.get('iss', '')).rstrip('/') != self.issuer:
+            raise self._fail(401, 'invalid_token', 'The token is from another issuer')
+        aud = claims.get('aud')
+        if self.resource not in (aud if isinstance(aud, list) else [aud]):
+            raise self._fail(401, 'invalid_token', 'The token is for another server')
+        if not isinstance(claims.get('exp'), (int, float)) or claims['exp'] + self.skew <= time.time():
+            raise self._fail(401, 'invalid_token', 'The token expired')
+        return claims
+
+    @staticmethod
+    def _view(claims: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            'sub': str(claims.get('sub')), 'email': claims.get('email'), 'client_id': claims.get('client_id', ''),
+            'scopes': [x for x in str(claims.get('scope', '')).split(' ') if x], 'org_id': claims.get('org_id'),
+            'expires_at': claims['exp'], 'dpop_bound': bool((claims.get('cnf') or {}).get('jkt')), 'claims': claims,
+        }
+
+    def verify_token(self, token: str) -> Dict[str, Any]:
+        """A bearer token alone (FastMCP's TokenVerifier): a DPoP-bound one is refused here."""
+        claims = self._claims(token)
+        if (claims.get('cnf') or {}).get('jkt'):
+            raise self._fail(401, 'invalid_token', 'This token is bound to a DPoP key: use verify() with the request')
+        return self._view(claims)
+
+    def verify(self, method: str, url: str, headers: Mapping[str, str]) -> Dict[str, Any]:
+        """A request's token, checked: ``{'sub', 'email', 'client_id', 'scopes', 'org_id', 'expires_at', 'dpop_bound', 'claims'}``."""
+        lower = {k.lower(): v for k, v in headers.items()}
+        scheme, _, token = str(lower.get('authorization', '')).strip().partition(' ')
+        if scheme.lower() not in ('bearer', 'dpop') or token.count('.') != 2:
+            raise self._fail(401, 'missing_token', 'A TouchQue access token is required')
+        claims = self._claims(token.strip())
+        jkt = (claims.get('cnf') or {}).get('jkt')
+        if jkt:
+            if scheme.lower() != 'dpop':
+                raise self._fail(401, 'invalid_token', 'This token is bound to a DPoP key: send it as DPoP with a proof')
+            self._check_proof(lower.get('dpop'), method, url, token.strip(), jkt)
+        return self._view(claims)
+
+    def _check_proof(self, proof: Optional[str], method: str, url: str, token: str, jkt: str) -> None:
+        try:
+            if not proof:
+                raise ValueError('missing')
+            h, p, s = proof.split('.')
+            head, claims = _json_part(h), _json_part(p)
+            jwk = head.get('jwk') or {}
+            if head.get('typ') != 'dpop+jwt' or 'd' in jwk or _thumbprint(jwk) != jkt:
+                raise ValueError('not the bound key')
+            if not _verify(f'{h}.{p}'.encode('ascii'), _b64d(s), head.get('alg', ''), _public_key(jwk)):
+                raise ValueError('signature')
+            u = urlparse(url)
+            if claims.get('htm') != method.upper() or claims.get('htu') != f'{u.scheme}://{u.netloc}{u.path}':
+                raise ValueError('htm/htu')
+            if abs(claims.get('iat', 0) - time.time()) > self.skew:
+                raise ValueError('iat')
+            if claims.get('ath') != _b64e(hashlib.sha256(token.encode('ascii')).digest()):
+                raise ValueError('ath')
+            now = time.time()
+            with self._lock:
+                for k in [k for k, until in self._proofs.items() if until < now]:
+                    del self._proofs[k]
+                if not claims.get('jti') or claims['jti'] in self._proofs:
+                    raise ValueError('jti used')
+                self._proofs[claims['jti']] = now + 2 * self.skew
+        except McpAuthError:
+            raise
+        except Exception as e:
+            raise self._fail(401, 'invalid_dpop_proof', f'DPoP proof: {e}')
+
+    def require_scope(self, claims: Mapping[str, Any], scope: str) -> None:
+        if scope not in claims.get('scopes', []):
+            raise self._fail(403, 'insufficient_scope', f'This needs the {scope} scope', scope)
+
+    def require_tool(self, claims: Mapping[str, Any], tool: str) -> None:
+        scope = self.tools.get(tool)
+        if not scope:
+            raise self._fail(403, 'insufficient_scope', f'No scope is set for the tool {tool}')
+        self.require_scope(claims, scope)

touchque/my_account.py

@@ -0,0 +1,173 @@
+"""TouchQue Login My Account API (/me/v1) from your server: the signed-in
+customer's own profile, sign-in methods, devices, apps and data, called with
+their access token for audience https://<domain>/me/.
+
+    me = login.my_account_token(session["refresh_token"], scope="read:me update:me")  # keep me.refresh_token
+    account = login.my_account(me.access_token)
+    account.get()["profile"]
+
+Security changes, the data export and deletion need a recent sign-in; when it
+is too old a MyAccountError with step_up True is raised: send the person
+through authorization_url(max_age=0) again.
+"""
+
+import re
+from typing import Any, Dict, Optional
+from urllib.parse import quote, urlsplit
+
+import requests
+
+from .config import _LOCAL_HOSTS
+from .exceptions import TouchQueException
+
+
+class MyAccountError(TouchQueException):
+    def __init__(self, code: str, status: int, description: Optional[str] = None, max_age: Optional[int] = None):
+        super().__init__(f"{code}: {description}" if description else code)
+        self.code = code
+        self.status = status
+        self.description = description
+        # True when the sign-in is too old for this change (RFC 9470).
+        self.step_up = code == "insufficient_user_authentication"
+        self.max_age = max_age
+
+
+def _seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _issuer_of(domain: str) -> str:
+    """https://<domain>. Plaintext http only on this machine (localhost, 127.0.0.1, ::1,
+    *.localhost), as for the API base_url: codes, tokens and secrets would travel in the clear."""
+    raw = domain.rstrip("/")
+    issuer = raw if raw.startswith(("http://", "https://")) else f"https://{raw}"
+    host = (urlsplit(issuer).hostname or "").lower()
+    if issuer.startswith("http://") and host not in _LOCAL_HOSTS and not host.endswith(".localhost"):
+        raise ValueError(f'refusing a plaintext http:// issuer for "{host}": use https://')
+    return issuer
+
+
+class MyAccount:
+    def __init__(self, domain: str, access_token: str, session: Optional[requests.Session] = None, timeout: float = 10.0):
+        if not domain or not access_token:
+            raise MyAccountError("config", 0, "domain and access_token are required")
+        try:
+            self.issuer = _issuer_of(domain)
+        except ValueError as err:
+            raise MyAccountError("config", 0, str(err))
+        self._token = access_token
+        self._http = session or requests.Session()
+        self.timeout = timeout
+
+    def account_page_url(self, section: Optional[str] = None) -> str:
+        """The hosted account page, optionally at 'security', 'devices' or 'privacy'."""
+        return f"{self.issuer}/account" + (f"/{section}" if section else "")
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        headers = {"Authorization": f"Bearer {self._token}", "Accept": "application/json"}
+        res = self._http.request(method, f"{self.issuer}/me/v1{path}", headers=headers, json=body, timeout=self.timeout)
+        if res.status_code == 204:
+            return None
+        try:
+            data = res.json()
+        except ValueError:
+            data = {}
+        if res.status_code >= 400:
+            challenge = res.headers.get("WWW-Authenticate", "") if getattr(res, "headers", None) else ""
+            m = re.search(r'max_age="?(\d+)"?', challenge)
+            raise MyAccountError(data.get("error") or f"http_{res.status_code}", res.status_code, data.get("error_description"), int(m.group(1)) if m else None)
+        return data
+
+    def get(self) -> Dict[str, Any]:
+        return self._call("GET", "")
+
+    def get_profile(self) -> Dict[str, Any]:
+        return self._call("GET", "/profile")
+
+    def update_profile(self, **changes: Any) -> Dict[str, Any]:
+        """name, given_name, family_name, nickname, locale, user_metadata (merged; None removes a key)."""
+        names = {"given_name": "givenName", "family_name": "familyName", "user_metadata": "userMetadata"}
+        return self._call("PATCH", "/profile", {names.get(k, k): v for k, v in changes.items()})
+
+    def authentication_methods(self) -> Dict[str, Any]:
+        return self._call("GET", "/authentication-methods")
+
+    def rename_passkey(self, passkey_id: str, label: str) -> None:
+        self._call("PATCH", f"/authentication-methods/passkeys/{_seg(passkey_id)}", {"label": label})
+
+    def remove_passkey(self, passkey_id: str) -> None:
+        """Needs a recent sign-in."""
+        self._call("DELETE", f"/authentication-methods/passkeys/{_seg(passkey_id)}")
+
+    def unlink_touchque_app(self) -> None:
+        """Needs a recent sign-in."""
+        self._call("DELETE", "/authentication-methods/touchque")
+
+    def set_email_codes(self, enabled: bool) -> Dict[str, Any]:
+        """Email codes as a second step. Needs a recent sign-in."""
+        return self._call("PUT", "/authentication-methods/email", {"enabled": enabled})
+
+    def start_sms_enrollment(self, phone: str) -> Dict[str, Any]:
+        """Texts a code to a new number for text-message codes. Needs a recent sign-in."""
+        return self._call("POST", "/authentication-methods/sms", {"phone": phone})
+
+    def verify_sms_enrollment(self, code: str) -> Dict[str, Any]:
+        """The code from that text: text-message codes are on. Needs a recent sign-in."""
+        return self._call("POST", "/authentication-methods/sms/verify", {"code": code})
+
+    def remove_sms_codes(self) -> None:
+        """Needs a recent sign-in."""
+        self._call("DELETE", "/authentication-methods/sms")
+
+    def unlink_identity(self, identity_id: str) -> None:
+        """Needs a recent sign-in."""
+        self._call("DELETE", f"/identities/{_seg(identity_id)}")
+
+    def stop_app_access(self, access_id: str) -> None:
+        """Apps stop using a linked account for the person (token vault: the identity's appAccess id);
+        signing in with it stays."""
+        self._call("DELETE", f"/app-access/{_seg(access_id)}")
+
+    def set_password(self, password: str) -> Dict[str, Any]:
+        """Sets or changes the password; other sessions end. Needs a recent sign-in."""
+        return self._call("PUT", "/password", {"password": password})
+
+    def remove_password(self) -> None:
+        """Needs a recent sign-in and another way to sign in."""
+        self._call("DELETE", "/password")
+
+    def change_email(self, email: str) -> Dict[str, Any]:
+        """A confirmation link goes to the new address. Needs a recent sign-in."""
+        return self._call("POST", "/email", {"email": email})
+
+    def send_verification_email(self) -> Dict[str, Any]:
+        return self._call("POST", "/email/verification")
+
+    def sessions(self) -> Dict[str, Any]:
+        return self._call("GET", "/sessions")
+
+    def end_session(self, session_id: str) -> None:
+        self._call("DELETE", f"/sessions/{_seg(session_id)}")
+
+    def end_other_sessions(self) -> Dict[str, Any]:
+        return self._call("DELETE", "/sessions")
+
+    def apps(self) -> Dict[str, Any]:
+        return self._call("GET", "/apps")
+
+    def revoke_app(self, client_id: str) -> Dict[str, Any]:
+        return self._call("DELETE", f"/apps/{_seg(client_id)}")
+
+    def consents(self) -> Dict[str, Any]:
+        return self._call("GET", "/consents")
+
+    def set_marketing(self, granted: bool) -> Dict[str, Any]:
+        return self._call("PUT", "/consents/marketing", {"granted": granted})
+
+    def export_data(self) -> Dict[str, Any]:
+        """Everything about the person (KVKK/GDPR). Needs a recent sign-in."""
+        return self._call("GET", "/export")
+
+    def delete_account(self) -> Dict[str, Any]:
+        """Erases the account at once. Needs delete:me and a recent sign-in."""
+        return self._call("DELETE", "")