t2em 0.6.0__py3-none-any.whl

t2em/__init__.py

@@ -0,0 +1,74 @@
+"""t2em — Python SDK for t2em.com (ТЗ docs/TZ_t2em.md §8.3).
+
+Zero-knowledge secret drops over a Blind Relay: the server stores only
+an AES-256-GCM envelope and can never derive the key. Bit-compatible
+with the TypeScript protocol `@t2em/protocol` — verified against
+`vectors/t2em-drop.v1.json`.
+
+Typical use::
+
+    from t2em import T2emClient, generate_x25519_keypair
+
+    client = T2emClient("https://t2em.com")
+
+    # Mode B (symmetric, key lives in the URL #fragment)
+    drop = client.push(secret="sk-live-...", ttl=300)
+    secret = client.pull_text(drop.url)
+
+    # Mode A (asymmetric, sealed to the recipient's X25519 pubkey)
+    keys = generate_x25519_keypair()
+    drop = client.push(secret="sk-live-...", recipient_pubkey=keys.public_key, ttl=300)
+    secret = client.pull_text(drop.url, recipient_privkey=keys.private_key)
+"""
+
+from .base64url import b64u_decode, b64u_encode, is_b64u_of_length
+from ._meta import SDK_VERSION, SDK_USER_AGENT
+from .client import CreatedDrop, ShareUrl, T2emClient
+from .envelope import Envelope, ModeAEnvelope, ModeBEnvelope, validate_envelope
+from .exceptions import HttpError, ProtocolError, T2emError, UsageError
+from .facade import pack_drop, unpack_drop
+from .fingerprint import fingerprint_pubkey, generate_fingerprint
+from .keyfile import KEYFILE_KIND, KEYFILE_TYPE, KEYFILE_VERSION, load_keyfile, write_keyfile
+from .keys import X25519KeyPair, generate_x25519_keypair
+from .protocol import (
+    HKDF_INFO_DROP_V1,
+    MAX_TTL_SECONDS,
+    MIN_TTL_SECONDS,
+    T2EM_PROTOCOL_VERSION,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "CreatedDrop",
+    "Envelope",
+    "HKDF_INFO_DROP_V1",
+    "KEYFILE_KIND",
+    "KEYFILE_TYPE",
+    "KEYFILE_VERSION",
+    "MAX_TTL_SECONDS",
+    "MIN_TTL_SECONDS",
+    "ModeAEnvelope",
+    "ModeBEnvelope",
+    "ProtocolError",
+    "HttpError",
+    "SDK_USER_AGENT",
+    "SDK_VERSION",
+    "ShareUrl",
+    "T2EM_PROTOCOL_VERSION",
+    "T2emClient",
+    "T2emError",
+    "UsageError",
+    "X25519KeyPair",
+    "b64u_decode",
+    "b64u_encode",
+    "fingerprint_pubkey",
+    "generate_fingerprint",
+    "generate_x25519_keypair",
+    "is_b64u_of_length",
+    "load_keyfile",
+    "pack_drop",
+    "unpack_drop",
+    "validate_envelope",
+    "write_keyfile",
+]

t2em/_meta.py

@@ -0,0 +1,8 @@
+"""SDK identity metadata — single source of the version string."""
+
+SDK_VERSION = "0.6.0"
+
+#: Identifying User-Agent (Cloudflare browser-integrity checks reject
+#: the bare `Python-urllib` default; the ecosystem is agent-friendly,
+#: so clients identify themselves — ТЗ §5.5, §8.6).
+SDK_USER_AGENT = f"t2em-python-sdk/{SDK_VERSION}"

t2em/base64url.py

@@ -0,0 +1,45 @@
+"""Base64URL helpers (RFC 4648 §5, no padding) — ТЗ §4.1.
+
+Strict mirror of `@t2em/protocol` `base64url.ts`: the same alphabet,
+the same rejection rules, so every wire string produced here is
+byte-identical to the TypeScript implementation.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+
+from .exceptions import ProtocolError
+
+_B64URL_ALPHABET = re.compile(r"^[A-Za-z0-9\-_]+$")
+
+
+def b64u_encode(data: bytes) -> str:
+    """Encode bytes to unpadded base64url."""
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def b64u_decode(text: str) -> bytes:
+    """Throwing strict decoder: rejects any non-base64url alphabet or padding."""
+    if not isinstance(text, str) or len(text) == 0:
+        raise ProtocolError("MALFORMED", "base64url string must be non-empty")
+    if not _B64URL_ALPHABET.match(text):
+        raise ProtocolError("MALFORMED", "not base64url (RFC 4648 §5, unpadded)")
+    if len(text) % 4 == 1:
+        raise ProtocolError("MALFORMED", "invalid base64url length")
+    pad = "=" * (-len(text) % 4)
+    try:
+        return base64.urlsafe_b64decode(text + pad)
+    except Exception as exc:  # binascii.Error and friends
+        raise ProtocolError("MALFORMED", f"invalid base64url: {exc}") from exc
+
+
+def is_b64u_of_length(text: object, byte_length: int) -> bool:
+    """True when `text` is valid base64url decoding to exactly `byte_length` bytes."""
+    if not isinstance(text, str):
+        return False
+    try:
+        return len(b64u_decode(text)) == byte_length
+    except ProtocolError:
+        return False

t2em/client.py

@@ -0,0 +1,313 @@
+"""Relay API client — `T2emClient` (ТЗ §5, §8.3).
+
+Speaks only the JSON contract (`Accept: application/json`) — no HTML
+parsing, ever (§8.1 API-first). Networking uses stdlib `urllib` only
+(§8.3: zero external network deps); the transport is injectable so the
+client is testable without sockets.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Optional, Sequence, Tuple, Union
+
+from .envelope import Envelope, validate_envelope
+from .exceptions import HttpError, ProtocolError, UsageError
+from .mode_a import pack_drop_asym, unpack_drop_asym
+from .mode_b import pack_drop_sym, unpack_drop_sym
+from ._meta import SDK_USER_AGENT
+from .protocol import MAX_TTL_SECONDS, MIN_TTL_SECONDS
+
+DEFAULT_BASE_URL = "https://t2em.com"
+
+_SECRET_RE = re.compile(r"^/s/([A-Za-z0-9_-]+)$")
+
+Transport = Callable[[str, str, Sequence[Tuple[str, str]], Optional[bytes]], "TransportResponse"]
+
+
+@dataclass(frozen=True)
+class TransportResponse:
+    """Raw HTTP response as seen by the transport."""
+
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+@dataclass(frozen=True)
+class CreatedDrop:
+    """`{ id, url, expires_in, delete_token }` from `POST /api/v1/drop`."""
+
+    id: str
+    url: str
+    expires_in: int
+    delete_token: str
+
+
+@dataclass(frozen=True)
+class ShareUrl:
+    """A share URL split into its relay id and the secret #fragment."""
+
+    id: str
+    #: None for Mode A URLs — they carry no fragment.
+    fragment: Optional[str]
+
+    @property
+    def has_fragment(self) -> bool:
+        return self.fragment is not None
+
+
+def parse_share_url(raw: str) -> ShareUrl:
+    """Parse `https://<host>/s/<id>[#<fragment>]` into its parts (§8.2)."""
+    if not isinstance(raw, str) or not raw.strip():
+        raise UsageError("url must be a non-empty string")
+    from urllib.parse import urlsplit
+
+    parts = urlsplit(raw.strip())
+    if parts.scheme not in ("https", "http"):
+        raise UsageError(f"unsupported url scheme: {parts.scheme!r}")
+    if not parts.netloc:
+        raise UsageError(f"invalid url: {raw}")
+    match = _SECRET_RE.match(parts.path)
+    if not match:
+        raise UsageError("url must point to a drop: https://<host>/s/<id>[#<key>]")
+    return ShareUrl(id=match.group(1), fragment=parts.fragment or None)
+
+
+def _urllib_transport(timeout: float) -> Transport:
+    """Default transport factory: stdlib urllib, no external deps (§8.3)."""
+
+    def transport(
+        method: str, url: str, headers: Sequence[Tuple[str, str]], body: Optional[bytes]
+    ) -> TransportResponse:
+        request = urllib.request.Request(url, data=body, method=method)
+        for key, value in headers:
+            request.add_header(key, value)
+        # Identify the client (default urllib UA is rejected by CF 1010).
+        request.add_header("user-agent", SDK_USER_AGENT)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return TransportResponse(
+                    status=response.status,
+                    headers={k: v for k, v in response.headers.items()},
+                    body=response.read(),
+                )
+        except urllib.error.HTTPError as err:
+            return TransportResponse(
+                status=err.code,
+                headers={k: v for k, v in err.headers.items()},
+                body=err.read(),
+            )
+
+    return transport
+
+
+class T2emClient:
+    """Client for the t2em.com Blind Relay (ТЗ §5).
+
+    Args:
+        base_url: relay origin, e.g. ``https://t2em.com``.
+        transport: injectable transport ``(method, url, headers, body)
+            -> TransportResponse`` for tests; defaults to stdlib urllib.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        transport: Optional[Transport] = None,
+        timeout: float = 15.0,
+    ) -> None:
+        if not isinstance(base_url, str) or not base_url.strip():
+            raise UsageError("base_url must be a non-empty string")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        if transport is not None:
+            self._transport: Transport = transport
+        else:
+            self._transport = _urllib_transport(timeout)
+
+    # ------------------------------------------------------------------
+    # Push / pull / delete
+    # ------------------------------------------------------------------
+
+    def push(
+        self,
+        *,
+        secret: Union[str, bytes, bytearray],
+        ttl: int = 300,
+        recipient_pubkey: Optional[Union[str, bytes, bytearray]] = None,
+    ) -> CreatedDrop:
+        """Create a drop — Mode B by default, Mode A with `recipient_pubkey`.
+
+        Returns `CreatedDrop` whose `url` carries the key in the
+        `#fragment` (Mode B only). The delete token is returned here
+        once — store it if you need `delete()`.
+        """
+        self._check_ttl(ttl)
+        plaintext = self._as_plaintext(secret)
+
+        if recipient_pubkey is not None:
+            from .mode_a import pack_drop_asym
+
+            envelope = pack_drop_asym(plaintext, recipient_pubkey)
+            fragment: Optional[str] = None
+        else:
+            envelope, fragment = pack_drop_sym(plaintext)
+
+        body = json.dumps({"envelope": envelope.to_dict(), "ttl": ttl}).encode("utf-8")
+        response = self._transport(
+            "POST",
+            f"{self._base_url}/api/v1/drop",
+            (("content-type", "application/json"), ("accept", "application/json")),
+            body,
+        )
+        payload = self._json_body(response.status, response.body)
+        if response.status != 201:
+            raise self._http_error(response.status, response.headers, response.body, payload)
+        try:
+            drop_id = payload["id"]
+            drop_url = payload["url"]
+            expires_in = payload["expires_in"]
+            delete_token = payload["delete_token"]
+        except (KeyError, TypeError) as exc:
+            raise ProtocolError("MALFORMED", f"relay 201 payload missing field: {exc}") from exc
+        if not all(
+            isinstance(x, str) for x in (drop_id, drop_url, delete_token)
+        ) or not isinstance(expires_in, int):
+            raise ProtocolError("MALFORMED", "relay 201 payload has unexpected field types")
+        # Mode B: the relay never sees the key — the #fragment is appended
+        # client-side, exactly like the Web UI and the CLI do (§4.3).
+        url = drop_url if fragment is None else f"{drop_url}#{fragment}"
+        return CreatedDrop(
+            id=drop_id, url=url, expires_in=expires_in, delete_token=delete_token
+        )
+
+    def pull_bytes(
+        self,
+        url: str,
+        *,
+        recipient_privkey: Optional[Union[str, bytes, bytearray]] = None,
+    ) -> bytes:
+        """Fetch and decrypt a drop; the relay copy is consumed (GETDEL).
+
+        Mode B needs the `#fragment` of the URL; Mode A needs the
+        recipient's X25519 private key.
+        """
+        parts = parse_share_url(url)
+        envelope = self._consume(parts.id)
+
+        if envelope.mode == "sym":
+            if not parts.fragment:
+                raise UsageError(
+                    "Mode B url carries no #fragment — the key is missing"
+                )
+            return unpack_drop_sym(envelope, parts.fragment)
+
+        # Mode A
+        if recipient_privkey is None:
+            raise UsageError(
+                "Mode A url requires recipient_privkey (e.g. from load_keyfile)"
+            )
+        return unpack_drop_asym(envelope, recipient_privkey)
+
+    def pull_text(
+        self,
+        url: str,
+        *,
+        recipient_privkey: Optional[Union[str, bytes, bytearray]] = None,
+    ) -> str:
+        """`pull_bytes` decoded as UTF-8 text (ТЗ §8.3 `pull_text`)."""
+        return self.pull_bytes(url, recipient_privkey=recipient_privkey).decode("utf-8")
+
+    def delete(self, url_or_id: str, delete_token: str) -> None:
+        """Delete a drop before TTL expiry (§5.4); idempotent 404 is NOT ok."""
+        raw = url_or_id.strip()
+        drop_id = parse_share_url(raw).id if "/s/" in raw else raw
+        if not re.fullmatch(r"[A-Za-z0-9_-]+", drop_id):
+            raise UsageError(f"invalid drop id: {drop_id!r}")
+        if not delete_token:
+            raise UsageError("delete_token is required")
+        response = self._transport(
+            "DELETE",
+            f"{self._base_url}/api/v1/drop/{drop_id}",
+            (("x-delete-token", delete_token), ("accept", "application/json")),
+            None,
+        )
+        if response.status != 200:
+            raise self._http_error(response.status, response.headers, response.body)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _consume(self, drop_id: str) -> Envelope:
+        response = self._transport(
+            "GET",
+            f"{self._base_url}/s/{drop_id}",
+            (("accept", "application/json"),),
+            None,
+        )
+        payload = self._json_body(response.status, response.body)
+        if response.status != 200:
+            raise self._http_error(response.status, response.headers, response.body, payload)
+        # §5.3 wire shape: { envelope: {...} }
+        if not isinstance(payload, dict) or "envelope" not in payload:
+            raise ProtocolError("MALFORMED", 'relay response missing "envelope" object')
+        return validate_envelope(payload["envelope"])
+
+    @staticmethod
+    def _check_ttl(ttl: int) -> None:
+        if not isinstance(ttl, int) or isinstance(ttl, bool):
+            raise UsageError("ttl must be an integer number of seconds")
+        if not MIN_TTL_SECONDS <= ttl <= MAX_TTL_SECONDS:
+            raise UsageError(
+                f"ttl must be between {MIN_TTL_SECONDS} and {MAX_TTL_SECONDS} seconds"
+            )
+
+    @staticmethod
+    def _as_plaintext(secret: Union[str, bytes, bytearray]) -> bytes:
+        if isinstance(secret, str):
+            return secret.encode("utf-8")
+        if isinstance(secret, (bytes, bytearray)):
+            return bytes(secret)
+        raise UsageError("secret must be str or bytes")
+
+    @staticmethod
+    def _json_body(status: int, body: bytes) -> Any:
+        if not body:
+            return None
+        try:
+            return json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            if 200 <= status < 300:
+                raise ProtocolError("MALFORMED", f"relay response is not valid JSON: {exc}") from exc
+            return None
+
+    @staticmethod
+    def _http_error(
+        status: int,
+        headers: Mapping[str, str],
+        body: bytes,
+        payload: Any = None,
+    ) -> HttpError:
+        retry_after: Optional[int] = None
+        raw_retry = headers.get("retry-after") if headers else None
+        if raw_retry is not None:
+            try:
+                retry_after = int(raw_retry)
+            except ValueError:
+                retry_after = None
+        code: Optional[str] = None
+        message = f"relay returned HTTP {status}"
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            err = payload["error"]
+            if isinstance(err.get("code"), str):
+                code = err["code"]
+            if isinstance(err.get("message"), str):
+                message = err["message"]
+        return HttpError(status, code, message, retry_after)

t2em/envelope.py

@@ -0,0 +1,162 @@
+"""Envelope shapes and validation — mirror of `@t2em/protocol` `envelope.ts`.
+
+The relay validates envelopes on write; the SDK validates envelopes it
+pulls before decrypting, so a hostile/broken relay cannot feed the
+crypto layer arbitrary bytes (§11.4 injection protection).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Union
+
+from .base64url import b64u_decode, is_b64u_of_length
+from .exceptions import ProtocolError
+from .protocol import GCM_TAG_BYTES, IV_BYTES, T2EM_PROTOCOL_VERSION, X25519_KEY_BYTES
+
+MAX_IV_BYTES = IV_BYTES
+MAX_EPHEMERAL_PUBKEY_BYTES = X25519_KEY_BYTES
+MAX_ED25519_SIG_BYTES = 64
+MAX_ED25519_PUBKEY_BYTES = 32
+
+
+@dataclass(frozen=True)
+class ModeBEnvelope:
+    """Mode B — symmetric #fragment bootstrap (ТЗ §4.3)."""
+
+    ciphertext: str
+    iv: str
+    mode: str = "sym"
+    v: int = T2EM_PROTOCOL_VERSION
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"v": self.v, "mode": self.mode, "ciphertext": self.ciphertext, "iv": self.iv}
+
+
+@dataclass(frozen=True)
+class ModeAEnvelope:
+    """Mode A — asymmetric E2EE on X25519 (ТЗ §4.2).
+
+    Optional Ed25519 sender fields (§5.2): ``sender_signature`` (64B
+    base64url) and ``sender_pubkey`` (32B base64url), preserved on
+    validation — TS and Python must agree bit-for-bit (§4.5 vectors).
+    """
+
+    ephemeral_pubkey: str
+    ciphertext: str
+    iv: str
+    mode: str = "x25519"
+    v: int = T2EM_PROTOCOL_VERSION
+    sender_signature: str | None = None
+    sender_pubkey: str | None = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {
+            "v": self.v,
+            "mode": self.mode,
+            "ephemeralPubKey": self.ephemeral_pubkey,
+            "ciphertext": self.ciphertext,
+            "iv": self.iv,
+        }
+        if self.sender_signature is not None:
+            out["senderSignature"] = self.sender_signature
+        if self.sender_pubkey is not None:
+            out["senderPubKey"] = self.sender_pubkey
+        return out
+
+
+Envelope = Union[ModeAEnvelope, ModeBEnvelope]
+
+_FORBIDDEN_KEYS = frozenset({"__proto__", "constructor", "prototype"})
+
+
+def _safe_json(value: Any) -> Dict[str, Any]:
+    """Prototype-safe parse guard (§11.4): reject poisoned keys outright."""
+    if not isinstance(value, dict):
+        raise ProtocolError("MALFORMED", "envelope must be a JSON object")
+    if any(k in _FORBIDDEN_KEYS for k in value):
+        raise ProtocolError("MALFORMED", "forbidden key in envelope")
+    return value
+
+
+def validate_envelope(value: Any) -> Envelope:
+    """Validate an unknown value as a protocol-v1 envelope.
+
+    Raises `ProtocolError` with code ``UNSUPPORTED_VERSION`` or
+    ``MALFORMED`` on any deviation; returns the narrowed envelope
+    otherwise.
+    """
+    v = _safe_json(value)
+
+    if v.get("v") != T2EM_PROTOCOL_VERSION:
+        if isinstance(v.get("v"), int):
+            raise ProtocolError("UNSUPPORTED_VERSION", f"envelope.v={v.get('v')}")
+        raise ProtocolError("MALFORMED", "envelope.v must be a number")
+
+    ciphertext = v.get("ciphertext")
+    if not isinstance(ciphertext, str) or len(ciphertext) == 0:
+        raise ProtocolError("MALFORMED", "ciphertext must be a non-empty base64url string")
+    iv = v.get("iv")
+    if not isinstance(iv, str) or not is_b64u_of_length(iv, MAX_IV_BYTES):
+        raise ProtocolError("MALFORMED", f"iv must be base64url of exactly {MAX_IV_BYTES} bytes")
+    try:
+        ct_len = len(b64u_decode(ciphertext))
+    except ProtocolError:
+        raise ProtocolError("MALFORMED", "ciphertext is not valid base64url") from None
+    if ct_len < GCM_TAG_BYTES:
+        raise ProtocolError("MALFORMED", f"ciphertext shorter than GCM tag ({GCM_TAG_BYTES} bytes)")
+
+    mode = v.get("mode")
+    if mode == "sym":
+        # §4.5 negative contract: a sym envelope carrying Mode A fields
+        # is malformed (cross-mode confusion, §4.5 vectors).
+        if (
+            v.get("ephemeralPubKey") is not None
+            or v.get("senderSignature") is not None
+            or v.get("senderPubKey") is not None
+        ):
+            raise ProtocolError(
+                "MALFORMED",
+                "sym envelope must not carry Mode A fields "
+                "(ephemeralPubKey/senderSignature/senderPubKey)",
+            )
+        return ModeBEnvelope(ciphertext=ciphertext, iv=iv)
+
+    if mode == "x25519":
+        eph = v.get("ephemeralPubKey")
+        if not isinstance(eph, str) or not is_b64u_of_length(eph, MAX_EPHEMERAL_PUBKEY_BYTES):
+            raise ProtocolError(
+                "MALFORMED",
+                f"ephemeralPubKey must be base64url of exactly {MAX_EPHEMERAL_PUBKEY_BYTES} bytes",
+            )
+        sig = v.get("senderSignature")
+        if sig is not None and (not isinstance(sig, str) or not is_b64u_of_length(sig, MAX_ED25519_SIG_BYTES)):
+            raise ProtocolError(
+                "MALFORMED",
+                "senderSignature must be base64url of exactly 64 bytes",
+            )
+        spk = v.get("senderPubKey")
+        if spk is not None and (not isinstance(spk, str) or not is_b64u_of_length(spk, MAX_ED25519_PUBKEY_BYTES)):
+            raise ProtocolError(
+                "MALFORMED",
+                "senderPubKey must be base64url of exactly 32 bytes",
+            )
+        return ModeAEnvelope(
+            ephemeral_pubkey=eph,
+            ciphertext=ciphertext,
+            iv=iv,
+            sender_signature=sig,
+            sender_pubkey=spk,
+        )
+
+    raise ProtocolError("MALFORMED", f"unknown envelope.mode: {mode!r}")
+
+
+def parse_envelope_json(text: str) -> Envelope:
+    """Parse + validate an envelope from relay JSON (safe re-raise)."""
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError("MALFORMED", f"relay response is not valid JSON: {exc}") from exc
+    return validate_envelope(raw)

t2em/exceptions.py

@@ -0,0 +1,54 @@
+"""Exception taxonomy (ТЗ §4.5) — mirrors the TS client errors.
+
+Integrators branch on `ProtocolError.code`, never on message text.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class T2emError(Exception):
+    """Base class for every t2em SDK error."""
+
+
+class UsageError(T2emError):
+    """Invalid caller input: bad URL, TTL out of range, wrong key length."""
+
+
+class ProtocolError(T2emError):
+    """Envelope-level failure (shape, version, or AEAD decryption).
+
+    Attributes:
+        code: ``MALFORMED`` | ``UNSUPPORTED_VERSION`` | ``DECRYPT_FAILED``
+            — the §4.5 taxonomy used by the relay and the TS SDK.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+class HttpError(T2emError):
+    """Non-success relay response carrying the §5.2 error JSON.
+
+    Attributes:
+        status: HTTP status code.
+        code: machine-readable error code from the body, if present.
+        message: human-readable message from the body or a fallback.
+        retry_after: parsed ``Retry-After`` header (seconds), if present.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: Optional[str],
+        message: str,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(f"HTTP {status}{f' ({code})' if code else ''}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.retry_after = retry_after