dominusnode 2.0.0__py3-none-any.whl

dominusnode/secret.py

@@ -0,0 +1,60 @@
+"""Secret wrapper for credentials the server returns exactly once."""
+
+from __future__ import annotations
+
+REDACTED = "[REDACTED]"
+
+
+class Secret:
+    """Wraps a credential (new API key, team key, ``dn_node_`` key).
+
+    ``str()``, ``repr()``, ``format()`` and JSON serialisation (via ``__json__``/``to_json``)
+    yield ``[REDACTED]``; call :meth:`reveal` for the value. The value lives in a
+    name-mangled slot so ``vars()``/``__dict__`` do not expose it.
+    """
+
+    __slots__ = ("__value",)
+
+    def __init__(self, value: str) -> None:
+        self.__value = value
+
+    def reveal(self) -> str:
+        return self.__value
+
+    @property
+    def prefix(self) -> str:
+        """First 8 characters, safe for logs."""
+        return self.__value[:8]
+
+    def __str__(self) -> str:
+        return REDACTED
+
+    def __repr__(self) -> str:
+        return f"Secret({REDACTED})"
+
+    def __format__(self, spec: str) -> str:
+        return format(REDACTED, spec)
+
+    def to_json(self) -> str:
+        return REDACTED
+
+    __json__ = to_json
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Secret) and other.__value == self.__value
+
+    def __hash__(self) -> int:
+        return hash(("Secret", self.__value))
+
+    def __reduce__(self) -> object:
+        raise TypeError("Secret cannot be pickled")
+
+
+def json_default(obj: object) -> object:
+    """``json.dumps(..., default=json_default)`` serialises Secret as ``[REDACTED]``."""
+    if isinstance(obj, Secret):
+        return REDACTED
+    to_json = getattr(obj, "to_json", None)
+    if callable(to_json):
+        return to_json()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")

dominusnode/signer.py

@@ -0,0 +1,56 @@
+"""Caller-supplied EIP-191 signer callback.
+
+The SDK has no crypto dependency. Wrap eth-account, web3.py, a KMS or an HSM::
+
+    from eth_account import Account
+    from eth_account.messages import encode_defunct
+
+    acct = Account.from_key(pk)
+
+    class MySigner:
+        address = acct.address
+        def sign_message(self, message: str) -> str:
+            return "0x" + acct.sign_message(encode_defunct(text=message)).signature.hex().removeprefix("0x")
+
+``sign_message`` MUST perform ``personal_sign`` over the exact UTF-8 string and return a
+65-byte 0x-hex signature. With ``AsyncDominusNodeClient`` it may be ``async def``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Generator, Union
+
+try:  # Python 3.8+
+    from typing import Protocol, runtime_checkable
+except ImportError:  # pragma: no cover
+    from typing_extensions import Protocol, runtime_checkable  # type: ignore
+
+from ._ops import Sign
+from .errors import ProtocolError, ValidationError, invalid_arg
+from .validation import validate_address, validate_signature
+
+
+@runtime_checkable
+class Signer(Protocol):
+    address: str
+
+    def sign_message(self, message: str) -> Union[str, Awaitable[str]]: ...
+
+
+def assert_signer(signer: Any, name: str = "signer") -> Any:
+    if signer is None or not callable(getattr(signer, "sign_message", None)):
+        raise invalid_arg(f"{name} must have an address and a sign_message(message) method")
+    validate_address(getattr(signer, "address", None), f"{name}.address")
+    return signer
+
+
+def sign(signer: Any, message: str, name: str = "signer") -> Generator[Any, Any, str]:
+    """Ask the signer for a signature (as an op) and validate its format; failures raise ProtocolError."""
+    try:
+        sig = yield Sign(signer, message)
+    except Exception as err:  # noqa: BLE001
+        raise ProtocolError(f"{name}.sign_message failed: {err}") from None
+    try:
+        return validate_signature(sig, f"{name} signature")
+    except ValidationError as err:
+        raise ProtocolError(err.message) from None

dominusnode/ssrf.py

@@ -0,0 +1,176 @@
+"""Client-side SSRF guard for proxy.fetch().
+
+The gateway and node re-check after their own DNS resolution; this layer fails
+fast and blocks DNS rebinding by resolving the name and checking EVERY address.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from typing import Callable, List, Optional
+from urllib.parse import SplitResult, urlsplit
+
+from .errors import ProxyError
+
+#: Resolver: hostname -> every address (A + AAAA). Injectable for tests.
+LookupAll = Callable[[str], List[str]]
+
+
+def default_lookup(hostname: str) -> List[str]:
+    infos = socket.getaddrinfo(hostname, None, proto=socket.IPPROTO_TCP)
+    return [str(info[4][0]) for info in infos]
+
+
+BLOCKED_HOSTNAMES = frozenset({"localhost", "localhost.localdomain", "ip6-localhost", "ip6-loopback"})
+BLOCKED_SUFFIXES = (".localhost", ".local", ".internal", ".arpa")
+
+_HEX = re.compile(r"^0x[0-9a-f]+\Z", re.IGNORECASE)
+_OCT = re.compile(r"^0[0-7]+\Z")
+_DEC = re.compile(r"^(0|[1-9][0-9]*)\Z")
+
+
+def normalize_ipv4(host: str) -> Optional[str]:
+    """Decode decimal/hex/octal/short IPv4 forms (2130706433, 0x7f000001, 0177.0.0.1, 127.1); None if not IPv4-like."""
+    parts = host.split(".")
+    if len(parts) < 1 or len(parts) > 4:
+        return None
+    nums: List[int] = []
+    for p in parts:
+        if _HEX.match(p):
+            nums.append(int(p, 16))
+        elif _OCT.match(p):
+            nums.append(int(p, 8))
+        elif _DEC.match(p):
+            nums.append(int(p, 10))
+        else:
+            return None
+    last = nums.pop()
+    if any(n > 255 for n in nums):
+        return None
+    rem = 4 - len(nums)
+    if last >= 2 ** (8 * rem):
+        return None
+    out = list(nums)
+    for i in range(rem - 1, -1, -1):
+        out.append((last >> (8 * i)) & 0xFF)
+    return ".".join(str(b) for b in out)
+
+
+def _is_private_v4(ip: str) -> bool:
+    a, b = (int(x) for x in ip.split(".")[:2])
+    return (
+        a in (0, 10, 127)
+        or (a == 169 and b == 254)
+        or (a == 172 and 16 <= b <= 31)
+        or (a == 192 and b == 168)
+        or (a == 100 and 64 <= b <= 127)
+        or (a == 192 and b == 0)  # 192.0.0.0/24 IETF + 192.0.2.0/24 docs
+        or (a == 198 and b in (18, 19))  # benchmarking
+        or a >= 224  # multicast, reserved, broadcast
+    )
+
+
+def is_private_ip(host: str) -> bool:
+    """True for private/reserved IPv4 (any spelling) and IPv6 literals; False for public IPs and non-IP names."""
+    ip = host
+    if ip.startswith("["):
+        ip = ip[1:]
+    if ip.endswith("]"):
+        ip = ip[:-1]
+    zone = ip.find("%")
+    if zone != -1:
+        ip = ip[:zone]
+    v4 = normalize_ipv4(ip)
+    if v4 is not None:
+        return _is_private_v4(v4)
+    try:
+        b = ipaddress.IPv6Address(ip).packed
+    except ValueError:
+        return False
+    zero10 = all(x == 0 for x in b[:10])
+    tail = ".".join(str(x) for x in b[12:])
+    if zero10 and b[10] == 0xFF and b[11] == 0xFF:
+        return _is_private_v4(tail)  # ::ffff:a.b.c.d
+    if zero10 and b[10] == 0 and b[11] == 0:
+        # ::, ::1 and IPv4-compatible ::a.b.c.d
+        return True if all(x == 0 for x in b[12:15]) else _is_private_v4(tail)
+    if b[:4] == b"\x00\x64\xff\x9b":
+        return _is_private_v4(tail)  # NAT64 64:ff9b::/96
+    if (b[0] & 0xFE) == 0xFC:
+        return True  # fc00::/7
+    if b[0] == 0xFE and (b[1] & 0xC0) == 0x80:
+        return True  # fe80::/10
+    if b[0] == 0xFE and (b[1] & 0xC0) == 0xC0:
+        return True  # fec0::/10
+    if b[0] == 0xFF:
+        return True  # multicast
+    if b[:4] == b"\x20\x01\x00\x00":
+        return True  # Teredo 2001::/32
+    if b[:2] == b"\x20\x02":
+        return True  # 6to4
+    if b[:4] == b"\x20\x01\x0d\xb8":
+        return True  # documentation
+    return False
+
+
+_HOST_RE = re.compile(r"^[a-z0-9._-]+\Z")
+
+
+def _is_ip_literal(host: str) -> bool:
+    try:
+        ipaddress.ip_address(host.split("%", 1)[0])
+        return True
+    except ValueError:
+        return False
+
+
+def validate_target_url(url: str) -> SplitResult:
+    """http(s) only, no userinfo, port empty/80/443, no local names or private literals."""
+    if not isinstance(url, str):
+        raise ProxyError("Invalid URL")
+    try:
+        u = urlsplit(url.strip())
+        port = u.port
+    except ValueError:
+        raise ProxyError("Invalid URL") from None
+    scheme = u.scheme.lower()
+    if scheme not in ("http", "https"):
+        raise ProxyError("Only http: and https: URLs are supported")
+    if "@" in u.netloc:
+        raise ProxyError("URLs with embedded credentials are not allowed")
+    if port is not None and port not in (80, 443):
+        raise ProxyError("Only ports 80 and 443 are reachable through the relay network")
+    host = (u.hostname or "").lower()
+    if host.endswith("."):
+        host = host[:-1]
+    if not host:
+        raise ProxyError("URL has no host")
+    if not _is_ip_literal(host) and not _HOST_RE.match(host):
+        raise ProxyError("Invalid URL")
+    if host in BLOCKED_HOSTNAMES or any(host.endswith(s) for s in BLOCKED_SUFFIXES):
+        raise ProxyError("Requests to local/internal hostnames are blocked")
+    if is_private_ip(host):
+        raise ProxyError("Requests to private/internal IP addresses are blocked")
+    return u
+
+
+def assert_public_resolution(hostname: str, lookup: Optional[LookupAll] = None) -> None:
+    """DNS-rebinding guard: resolve and reject if resolution fails, is empty, or ANY address is private."""
+    host = hostname.strip("[]")
+    if host.endswith("."):
+        host = host[:-1]
+    if _is_ip_literal(host) or normalize_ipv4(host) is not None:
+        if is_private_ip(host):
+            raise ProxyError("Requests to private/internal IP addresses are blocked")
+        return
+    try:
+        addrs = (lookup or default_lookup)(host)
+    except Exception:
+        raise ProxyError(f"DNS resolution failed for {host}") from None
+    if not addrs:
+        raise ProxyError(f"DNS resolution returned no addresses for {host}")
+    for a in addrs:
+        if is_private_ip(str(a)):
+            raise ProxyError("Hostname resolves to a private/internal IP address (blocked)")

dominusnode/token_manager.py

@@ -0,0 +1,150 @@
+"""JWT access/refresh pair holders (internal). clear() keeps the refresh callback."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import threading
+import time
+from typing import Awaitable, Callable, Optional, Tuple
+
+from .constants import TOKEN_REFRESH_BUFFER_SECONDS
+from .errors import AuthenticationError
+
+#: refresh_token -> (access_token, new_refresh_token or None)
+RefreshResult = Tuple[str, Optional[str]]
+
+
+def is_expired(token: str) -> bool:
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return True
+        seg = parts[1] + "=" * (-len(parts[1]) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(seg))
+        exp = payload.get("exp") if isinstance(payload, dict) else None
+        if not isinstance(exp, (int, float)) or isinstance(exp, bool):
+            return True
+        return exp < time.time() + TOKEN_REFRESH_BUFFER_SECONDS
+    except Exception:
+        return True
+
+
+class _BaseTokenManager:
+    def __init__(self) -> None:
+        self._access: Optional[str] = None
+        self._refresh: Optional[str] = None
+
+    def set_tokens(self, access: str, refresh: Optional[str] = None) -> None:
+        self._access = access
+        if refresh:
+            self._refresh = refresh
+
+    @property
+    def access_token(self) -> Optional[str]:
+        return self._access
+
+    @property
+    def refresh_token(self) -> Optional[str]:
+        return self._refresh
+
+    def has_tokens(self) -> bool:
+        return self._access is not None or self._refresh is not None
+
+    def _clear_tokens(self) -> None:
+        self._access = None
+        self._refresh = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}([REDACTED])"
+
+    __str__ = __repr__
+
+    def to_json(self) -> str:
+        return "[REDACTED]"
+
+
+class TokenManager(_BaseTokenManager):
+    def __init__(self) -> None:
+        super().__init__()
+        self._refresh_fn: Optional[Callable[[str], RefreshResult]] = None
+        self._lock = threading.Lock()
+
+    def set_refresh_function(self, fn: Callable[[str], RefreshResult]) -> None:
+        self._refresh_fn = fn
+
+    def has_refresh_function(self) -> bool:
+        return self._refresh_fn is not None
+
+    def get_valid_token(self) -> str:
+        if self._access and not is_expired(self._access):
+            return self._access
+        return self.force_refresh()
+
+    def force_refresh(self) -> str:
+        """Refresh regardless of expiry. Concurrent callers share one refresh (lock + re-check)."""
+        before = self._access
+        with self._lock:
+            if self._access is not None and self._access != before and not is_expired(self._access):
+                return self._access  # another thread refreshed while we waited
+            if not self._refresh or not self._refresh_fn:
+                raise AuthenticationError("No valid token and cannot refresh")
+            try:
+                access, refresh = self._refresh_fn(self._refresh)
+            except Exception:
+                self._clear_tokens()
+                raise
+            self._access = access
+            if refresh:
+                self._refresh = refresh
+            return access
+
+    def clear(self) -> None:
+        """Drop tokens. Does NOT drop the refresh function (reconnecting must keep working)."""
+        self._clear_tokens()
+
+
+class AsyncTokenManager(_BaseTokenManager):
+    def __init__(self) -> None:
+        super().__init__()
+        self._refresh_fn: Optional[Callable[[str], Awaitable[RefreshResult]]] = None
+        self._inflight: Optional["asyncio.Future[str]"] = None
+
+    def set_refresh_function(self, fn: Callable[[str], Awaitable[RefreshResult]]) -> None:
+        self._refresh_fn = fn
+
+    def has_refresh_function(self) -> bool:
+        return self._refresh_fn is not None
+
+    async def get_valid_token(self) -> str:
+        if self._access and not is_expired(self._access):
+            return self._access
+        return await self.force_refresh()
+
+    async def force_refresh(self) -> str:
+        if self._inflight is not None:
+            return await asyncio.shield(self._inflight)
+        if not self._refresh or not self._refresh_fn:
+            raise AuthenticationError("No valid token and cannot refresh")
+        fut: "asyncio.Future[str]" = asyncio.get_running_loop().create_future()
+        self._inflight = fut
+        try:
+            access, refresh = await self._refresh_fn(self._refresh)
+            self._access = access
+            if refresh:
+                self._refresh = refresh
+            fut.set_result(access)
+            return access
+        except BaseException as err:
+            self._clear_tokens()
+            fut.set_exception(err)
+            fut.exception()  # mark retrieved
+            raise
+        finally:
+            if self._inflight is fut:
+                self._inflight = None
+
+    def clear(self) -> None:
+        self._clear_tokens()
+        self._inflight = None

dominusnode/types.py

@@ -0,0 +1,99 @@
+"""Documentation-only TypedDicts for the main results (wire keys are camelCase, as the server sends them)."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+try:
+    from typing import TypedDict
+except ImportError:  # pragma: no cover
+    from typing_extensions import TypedDict  # type: ignore
+
+from .secret import Secret
+
+
+class Money(TypedDict):
+    musd: str  # integer µUSD
+    usd: str  # 6 decimals
+
+
+class ConnectResult(TypedDict, total=False):
+    mfaRequired: bool
+    userId: str
+
+
+class ActiveSession(TypedDict):
+    id: str
+    startedAt: str
+    status: str
+
+
+class CreatedApiKey(TypedDict):
+    id: str
+    prefix: str
+    label: str
+    created_at: str
+    key: Secret
+
+
+class PowChallenge(TypedDict):
+    challengeId: str
+    prefix: str
+    difficulty: int
+    algorithm: str
+    expiresAt: str
+
+
+class NodeChallenge(TypedDict):
+    nonce: str
+    attestationText: str
+    attestationVersion: int
+    policyVersion: int
+    message: str
+    expiresAt: str
+    powChallenge: PowChallenge
+
+
+class RegisteredNode(TypedDict):
+    nodeId: str
+    status: str
+    attestationVersion: int
+    nodeKey: Secret
+
+
+class Payout(TypedDict, total=False):
+    id: str
+    amount: Money
+    trigger: str
+    status: str  # pending held_tax held_frozen submitted confirmed failed reversed
+    txHash: Optional[str]
+    createdAt: str
+    failureReason: Optional[str]
+    address: str
+    chain: str
+    updatedAt: str
+
+
+class AgenticWallet(TypedDict):
+    id: str
+    label: str
+    balanceCents: int
+    spendingLimitCents: int
+    dailyLimitCents: Optional[int]
+    allowedDomains: Optional[List[str]]
+    status: str
+    createdAt: str
+
+
+class PricingEntry(TypedDict):
+    ipClass: str
+    pricePerGbMusd: str
+
+
+class NetworkPricing(TypedDict):
+    currency: str
+    unit: str
+    prices: List[PricingEntry]
+    nodeShare: List[Dict[str, object]]
+    maturationHours: int
+    rails: List[str]

dominusnode/validation.py

@@ -0,0 +1,117 @@
+"""Client-side argument validation. Failures raise ValidationError(code=INVALID_ARGUMENT) before any request."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any, Mapping, Optional, Union
+from urllib.parse import quote, urlencode
+
+from .constants import MAX_AMOUNT_CENTS
+from .errors import invalid_arg
+
+ETH_ADDRESS_RE = re.compile(r"^0x[0-9a-fA-F]{40}\Z")
+EIP191_SIGNATURE_RE = re.compile(r"^0x[0-9a-fA-F]{130}\Z")
+MAX_SIGNATURE_LENGTH = 200
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z", re.IGNORECASE)
+HEX64_RE = re.compile(r"^[0-9a-f]{64}\Z")
+IDEMPOTENCY_KEY_RE = re.compile(r"^[A-Za-z0-9_-]{8,120}\Z")
+API_KEY_RE = re.compile(r"^dn_(live|test)_[A-Za-z0-9_-]{8,200}\Z")
+_MUSD_RE = re.compile(r"^[1-9][0-9]{0,15}\Z")
+
+MusdInput = Union[int, str]
+
+
+def _is_int(v: Any) -> bool:
+    # bool is an int subclass; floats (incl. NaN/Infinity) are never accepted.
+    return isinstance(v, int) and not isinstance(v, bool)
+
+
+def validate_api_key(api_key: Any) -> str:
+    if not isinstance(api_key, str) or not API_KEY_RE.match(api_key):
+        raise invalid_arg("api_key must be a dn_live_ or dn_test_ key")
+    return api_key
+
+
+def validate_address(address: Any, name: str = "address") -> str:
+    if not isinstance(address, str) or not ETH_ADDRESS_RE.match(address):
+        raise invalid_arg(f"{name} must be an Ethereum address (0x followed by 40 hex characters)")
+    return address
+
+
+def validate_signature(signature: Any, name: str = "signature") -> str:
+    if not isinstance(signature, str):
+        raise invalid_arg(f"{name} must be a string")
+    if len(signature) > MAX_SIGNATURE_LENGTH:
+        raise invalid_arg(f"{name} must not exceed {MAX_SIGNATURE_LENGTH} characters")
+    if not EIP191_SIGNATURE_RE.match(signature):
+        raise invalid_arg(f"{name} must be an EIP-191 signature (0x followed by 130 hex characters)")
+    return signature
+
+
+def validate_cents(amount_cents: Any, name: str = "amount_cents", allow_zero: bool = False) -> int:
+    ok = _is_int(amount_cents) and (amount_cents >= 0 if allow_zero else amount_cents > 0) and amount_cents <= MAX_AMOUNT_CENTS
+    if not ok:
+        raise invalid_arg(f"{name} must be an integer {'>= 0' if allow_zero else '> 0'} and <= {MAX_AMOUNT_CENTS}")
+    return int(amount_cents)
+
+
+def to_musd(v: Any, minimum: int, maximum: int, name: str = "amount_musd") -> str:
+    """Normalise a µUSD amount (int or digit string) to its canonical decimal string; enforce [minimum, maximum]."""
+    if _is_int(v):
+        n = int(v)
+    elif isinstance(v, str) and _MUSD_RE.match(v):
+        n = int(v)
+    else:
+        raise invalid_arg(f"{name} must be a positive integer number of µUSD (int or digit string)")
+    if n < minimum or n > maximum:
+        raise invalid_arg(f"{name} must be between {minimum} and {maximum} µUSD")
+    return str(n)
+
+
+def new_idempotency_key() -> str:
+    """``"dn-" + UUIDv4`` (fits [A-Za-z0-9_-]{8,120})."""
+    return f"dn-{uuid.uuid4()}"
+
+
+def validate_idempotency_key(key: Any) -> str:
+    if not isinstance(key, str) or not IDEMPOTENCY_KEY_RE.match(key):
+        raise invalid_arg("idempotency_key must be 8-120 characters of [A-Za-z0-9_-]")
+    return key
+
+
+def validate_uuid(v: Any, name: str) -> str:
+    if not isinstance(v, str) or not UUID_RE.match(v):
+        raise invalid_arg(f"{name} must be a UUID")
+    return v
+
+
+def validate_non_empty(v: Any, name: str, maximum: int = 256) -> str:
+    if not isinstance(v, str) or len(v) == 0 or len(v) > maximum:
+        raise invalid_arg(f"{name} must be a non-empty string (max {maximum})")
+    return v
+
+
+def validate_int_range(v: Any, name: str, minimum: int, maximum: int) -> int:
+    if not _is_int(v) or v < minimum or v > maximum:
+        raise invalid_arg(f"{name} must be an integer in [{minimum}, {maximum}]")
+    return int(v)
+
+
+def validate_optional_int(v: Any, name: str) -> Optional[int]:
+    """Pagination values passed through to the server: integers only (no floats/NaN)."""
+    if v is None:
+        return None
+    if not _is_int(v):
+        raise invalid_arg(f"{name} must be an integer")
+    return int(v)
+
+
+def seg(v: str) -> str:
+    """Path segment encoder (encodeURIComponent semantics) for every user-supplied path parameter."""
+    return quote(str(v), safe="-_.!~*'()")
+
+
+def qs(params: Mapping[str, Any]) -> str:
+    items = [(k, str(v)) for k, v in params.items() if v is not None]
+    return f"?{urlencode(items)}" if items else ""