dominusnode 1.0.0__py3-none-any.whl

dominusnode/usage.py

@@ -0,0 +1,230 @@
+"""Usage resource -- usage stats, daily aggregation, top hosts, and CSV export."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import (
+    DailyUsage,
+    TopHost,
+    UsagePagination,
+    UsagePeriod,
+    UsageRecord,
+    UsageResponse,
+    UsageSummary,
+)
+
+
+def _parse_usage_response(data: dict) -> UsageResponse:
+    s = data["summary"]
+    summary = UsageSummary(
+        total_bytes=s["totalBytes"],
+        total_cost_cents=s["totalCostCents"],
+        request_count=s["requestCount"],
+        total_gb=s["totalGB"],
+        total_cost_usd=s["totalCostUsd"],
+    )
+
+    records = [
+        UsageRecord(
+            id=r["id"],
+            session_id=r["sessionId"],
+            bytes_in=r["bytesIn"],
+            bytes_out=r["bytesOut"],
+            total_bytes=r["totalBytes"],
+            cost_cents=r["costCents"],
+            proxy_type=r.get("proxyType", ""),
+            target_host=r.get("targetHost", ""),
+            created_at=str(r.get("createdAt", "")),
+        )
+        for r in data.get("records", [])
+    ]
+
+    p = data.get("pagination", {})
+    pagination = UsagePagination(
+        limit=p.get("limit", 0),
+        offset=p.get("offset", 0),
+        total=p.get("total", 0),
+    )
+
+    pr = data.get("period", {})
+    period = UsagePeriod(
+        since=str(pr.get("since", "")),
+        until=str(pr.get("until", "")),
+    )
+
+    return UsageResponse(
+        summary=summary,
+        records=records,
+        pagination=pagination,
+        period=period,
+    )
+
+
+def _build_date_params(
+    since: Optional[str],
+    until: Optional[str],
+) -> dict:
+    params: dict = {}
+    if since:
+        params["since"] = since
+    if until:
+        params["until"] = until
+    return params
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class UsageResource:
+    """Synchronous usage operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def get(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        limit: int = 200,
+        offset: int = 0,
+    ) -> UsageResponse:
+        """Get usage records with summary."""
+        params = _build_date_params(since, until)
+        params["limit"] = limit
+        params["offset"] = offset
+        data = self._http.get("/api/usage", params=params)
+        return _parse_usage_response(data)
+
+    def get_daily(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> List[DailyUsage]:
+        """Get daily usage aggregation for charts."""
+        params = _build_date_params(since, until)
+        data = self._http.get("/api/usage/daily", params=params)
+        return [
+            DailyUsage(
+                date=d["date"],
+                total_bytes=d["totalBytes"],
+                total_gb=d["totalGB"],
+                total_cost_cents=d["totalCostCents"],
+                total_cost_usd=d["totalCostUsd"],
+                request_count=d["requestCount"],
+            )
+            for d in data.get("days", [])
+        ]
+
+    def get_top_hosts(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[TopHost]:
+        """Get top target hosts by bandwidth."""
+        params = _build_date_params(since, until)
+        params["limit"] = limit
+        data = self._http.get("/api/usage/top-hosts", params=params)
+        return [
+            TopHost(
+                target_host=h["targetHost"],
+                total_bytes=h["totalBytes"],
+                total_gb=h["totalGB"],
+                request_count=h["requestCount"],
+            )
+            for h in data.get("hosts", [])
+        ]
+
+    def export_csv(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> str:
+        """Export usage records as CSV text."""
+        params = _build_date_params(since, until)
+        resp = self._http.get_raw("/api/usage/export", params=params)
+        return resp.text
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncUsageResource:
+    """Asynchronous usage operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        limit: int = 200,
+        offset: int = 0,
+    ) -> UsageResponse:
+        params = _build_date_params(since, until)
+        params["limit"] = limit
+        params["offset"] = offset
+        data = await self._http.get("/api/usage", params=params)
+        return _parse_usage_response(data)
+
+    async def get_daily(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> List[DailyUsage]:
+        params = _build_date_params(since, until)
+        data = await self._http.get("/api/usage/daily", params=params)
+        return [
+            DailyUsage(
+                date=d["date"],
+                total_bytes=d["totalBytes"],
+                total_gb=d["totalGB"],
+                total_cost_cents=d["totalCostCents"],
+                total_cost_usd=d["totalCostUsd"],
+                request_count=d["requestCount"],
+            )
+            for d in data.get("days", [])
+        ]
+
+    async def get_top_hosts(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[TopHost]:
+        params = _build_date_params(since, until)
+        params["limit"] = limit
+        data = await self._http.get("/api/usage/top-hosts", params=params)
+        return [
+            TopHost(
+                target_host=h["targetHost"],
+                total_bytes=h["totalBytes"],
+                total_gb=h["totalGB"],
+                request_count=h["requestCount"],
+            )
+            for h in data.get("hosts", [])
+        ]
+
+    async def export_csv(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> str:
+        params = _build_date_params(since, until)
+        resp = await self._http.get_raw("/api/usage/export", params=params)
+        return resp.text

dominusnode/wallet.py

@@ -0,0 +1,189 @@
+"""Wallet resource -- balance, transactions, top-ups, and forecasting."""
+
+from __future__ import annotations
+
+import math
+from typing import List, Optional
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import CryptoInvoice, PaypalOrder, StripeCheckout, Wallet, WalletForecast, WalletTransaction
+
+
+def _validate_amount_cents(value: int, name: str = "amount_cents") -> None:
+    """Validate that a financial amount is a positive integer within PostgreSQL int4 range."""
+    if not isinstance(value, int) or value <= 0 or value > 2_147_483_647:
+        raise ValueError(f"{name} must be a positive integer <= 2,147,483,647")
+
+
+def _parse_wallet(data: dict) -> Wallet:
+    return Wallet(
+        balance_cents=data["balanceCents"],
+        balance_usd=data["balanceUsd"],
+        currency=data.get("currency", "usd"),
+        last_topped_up=data.get("lastToppedUp"),
+    )
+
+
+def _parse_transaction(tx: dict) -> WalletTransaction:
+    return WalletTransaction(
+        id=tx["id"],
+        type=tx["type"],
+        amount_cents=tx["amountCents"],
+        amount_usd=tx["amountUsd"],
+        description=tx.get("description", ""),
+        payment_provider=tx.get("paymentProvider"),
+        created_at=str(tx.get("createdAt", "")),
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class WalletResource:
+    """Synchronous wallet operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def get_balance(self) -> Wallet:
+        """Get current wallet balance."""
+        data = self._http.get("/api/wallet")
+        return _parse_wallet(data)
+
+    def get_transactions(self, *, limit: int = 50, offset: int = 0) -> List[WalletTransaction]:
+        """Get wallet transaction history."""
+        data = self._http.get("/api/wallet/transactions", params={"limit": limit, "offset": offset})
+        return [_parse_transaction(tx) for tx in data.get("transactions", [])]
+
+    def top_up_stripe(self, amount_cents: int) -> StripeCheckout:
+        """Create a Stripe checkout session for wallet top-up.
+
+        Args:
+            amount_cents: Amount in cents (e.g. 1000 = $10.00).
+        """
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = self._http.post("/api/wallet/topup/stripe", json={"amountCents": amount_cents})
+        return StripeCheckout(
+            session_id=data["sessionId"],
+            url=data["url"],
+        )
+
+    def top_up_crypto(self, amount_usd: float, currency: str) -> CryptoInvoice:
+        """Create a crypto invoice for wallet top-up.
+
+        Args:
+            amount_usd: Amount in USD (min $10.00).
+            currency: Crypto currency code (btc, eth, xmr, sol, zec).
+        """
+        if not isinstance(amount_usd, (int, float)) or math.isnan(amount_usd) or math.isinf(amount_usd):
+            raise ValueError("amount_usd must be a finite number")
+        if amount_usd < 10:
+            raise ValueError("Minimum crypto top-up is $10.00")
+        # Validate amount_usd converted to cents stays within int4 range
+        amount_cents_approx = int(amount_usd * 100)
+        _validate_amount_cents(amount_cents_approx, "amount_usd (as cents)")
+        data = self._http.post(
+            "/api/wallet/topup/crypto",
+            json={"amountUsd": amount_usd, "currency": currency},
+        )
+        return CryptoInvoice(
+            invoice_id=data["invoiceId"],
+            invoice_url=data["invoiceUrl"],
+            pay_currency=data["payCurrency"],
+            price_amount=data["priceAmount"],
+        )
+
+    def top_up_paypal(self, amount_cents: int) -> PaypalOrder:
+        """Create a PayPal order for wallet top-up.
+
+        Args:
+            amount_cents: Amount in cents (min 500 = $5.00).
+        """
+        _validate_amount_cents(amount_cents, "amount_cents")
+        if amount_cents < 500:
+            raise ValueError("Minimum PayPal top-up is $5.00 (500 cents)")
+        data = self._http.post("/api/wallet/topup/paypal", json={"amountCents": amount_cents})
+        return PaypalOrder(
+            order_id=data["orderId"],
+            approval_url=data["approvalUrl"],
+            amount_cents=data["amountCents"],
+        )
+
+    def get_forecast(self) -> WalletForecast:
+        """Get wallet balance forecast based on recent usage."""
+        data = self._http.get("/api/wallet/forecast")
+        return WalletForecast(
+            daily_avg_cents=data["dailyAvgCents"],
+            days_remaining=data.get("daysRemaining"),
+            trend=data["trend"],
+            trend_pct=data["trendPct"],
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncWalletResource:
+    """Asynchronous wallet operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get_balance(self) -> Wallet:
+        data = await self._http.get("/api/wallet")
+        return _parse_wallet(data)
+
+    async def get_transactions(self, *, limit: int = 50, offset: int = 0) -> List[WalletTransaction]:
+        data = await self._http.get("/api/wallet/transactions", params={"limit": limit, "offset": offset})
+        return [_parse_transaction(tx) for tx in data.get("transactions", [])]
+
+    async def top_up_stripe(self, amount_cents: int) -> StripeCheckout:
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = await self._http.post("/api/wallet/topup/stripe", json={"amountCents": amount_cents})
+        return StripeCheckout(
+            session_id=data["sessionId"],
+            url=data["url"],
+        )
+
+    async def top_up_crypto(self, amount_usd: float, currency: str) -> CryptoInvoice:
+        if not isinstance(amount_usd, (int, float)) or math.isnan(amount_usd) or math.isinf(amount_usd):
+            raise ValueError("amount_usd must be a finite number")
+        if amount_usd < 10:
+            raise ValueError("Minimum crypto top-up is $10.00")
+        # Validate amount_usd converted to cents stays within int4 range
+        amount_cents_approx = int(amount_usd * 100)
+        _validate_amount_cents(amount_cents_approx, "amount_usd (as cents)")
+        data = await self._http.post(
+            "/api/wallet/topup/crypto",
+            json={"amountUsd": amount_usd, "currency": currency},
+        )
+        return CryptoInvoice(
+            invoice_id=data["invoiceId"],
+            invoice_url=data["invoiceUrl"],
+            pay_currency=data["payCurrency"],
+            price_amount=data["priceAmount"],
+        )
+
+    async def top_up_paypal(self, amount_cents: int) -> PaypalOrder:
+        _validate_amount_cents(amount_cents, "amount_cents")
+        if amount_cents < 500:
+            raise ValueError("Minimum PayPal top-up is $5.00 (500 cents)")
+        data = await self._http.post("/api/wallet/topup/paypal", json={"amountCents": amount_cents})
+        return PaypalOrder(
+            order_id=data["orderId"],
+            approval_url=data["approvalUrl"],
+            amount_cents=data["amountCents"],
+        )
+
+    async def get_forecast(self) -> WalletForecast:
+        data = await self._http.get("/api/wallet/forecast")
+        return WalletForecast(
+            daily_avg_cents=data["dailyAvgCents"],
+            days_remaining=data.get("daysRemaining"),
+            trend=data["trend"],
+            trend_pct=data["trendPct"],
+        )

dominusnode/wallet_auth.py

@@ -0,0 +1,241 @@
+"""Wallet-based authentication using EIP-191 signed messages."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+from dataclasses import dataclass
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .token_manager import AsyncTokenManager, TokenManager
+from .types import LoginResult, User
+
+# Ethereum address: 0x followed by 40 hex characters
+_ETH_ADDRESS_RE = re.compile(r"^0x[0-9a-fA-F]{40}$")
+
+# EIP-191 signature format: 0x prefix + 130 hex chars (65 bytes)
+_EIP191_SIGNATURE_RE = re.compile(r"^0x[0-9a-fA-F]{130}$")
+_MAX_SIGNATURE_LENGTH = 200
+
+
+def _validate_address(address: str) -> None:
+    """Validate Ethereum address format."""
+    if not address or not isinstance(address, str):
+        raise ValueError("address is required and must be a string")
+    if not _ETH_ADDRESS_RE.match(address):
+        raise ValueError(
+            "address must be a valid Ethereum address (0x followed by 40 hex characters)"
+        )
+
+
+def _validate_signature(signature: str) -> None:
+    """Validate EIP-191 signature format."""
+    if not signature or not isinstance(signature, str):
+        raise ValueError("signature is required and must be a string")
+    # Max length check before regex
+    if len(signature) > _MAX_SIGNATURE_LENGTH:
+        raise ValueError(
+            f"signature must not exceed {_MAX_SIGNATURE_LENGTH} characters"
+        )
+    # EIP-191 format validation
+    if not _EIP191_SIGNATURE_RE.match(signature):
+        raise ValueError(
+            "signature must be a valid EIP-191 signature (0x followed by 130 hex characters)"
+        )
+
+
+@dataclass(frozen=True)
+class WalletChallenge:
+    """Challenge returned by the wallet/challenge endpoint."""
+    challenge: str
+    expires_at: str
+
+
+@dataclass(frozen=True, repr=False)
+class WalletVerifyResult:
+    """Result from wallet/verify -- includes JWT tokens and user.
+
+    When ``mfa_required`` is ``True``, the caller must complete MFA
+    verification using ``auth.verify_mfa(code, mfa_challenge_token=result.mfa_challenge_token)``
+    before the client is fully authenticated. In this case ``token`` and
+    ``refresh_token`` will be empty strings.
+    """
+    token: str
+    refresh_token: str
+    user: User
+    mfa_required: bool = False
+    mfa_challenge_token: Optional[str] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"WalletVerifyResult(user={self.user!r}, mfa_required={self.mfa_required}, "
+            f"token='[REDACTED]', refresh_token='[REDACTED]')"
+        )
+
+
+@dataclass(frozen=True)
+class WalletLinkResult:
+    """Result from wallet/link."""
+    success: bool
+    wallet_address: str
+
+
+def _parse_verify_result(data: dict) -> WalletVerifyResult:
+    """Parse verify response into typed result.
+
+    Detect MFA-required responses so callers know to complete MFA
+    instead of silently returning empty tokens.
+    """
+    if data.get("mfaRequired"):
+        return WalletVerifyResult(
+            token="",
+            refresh_token="",
+            user=User(id="", email="", created_at=""),
+            mfa_required=True,
+            mfa_challenge_token=data.get("mfaChallengeToken"),
+        )
+    user_data = data.get("user", {})
+    user = User(
+        id=user_data.get("id", ""),
+        email=user_data.get("email", ""),
+        created_at=str(user_data.get("created_at", "")),
+        is_admin=user_data.get("is_admin", False),
+    )
+    return WalletVerifyResult(
+        token=data.get("token", ""),
+        refresh_token=data.get("refreshToken", ""),
+        user=user,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class WalletAuthResource:
+    """Synchronous wallet-based authentication operations."""
+
+    def __init__(self, http: SyncHttpClient, tokens: TokenManager) -> None:
+        self._http = http
+        self._tokens = tokens
+
+    def challenge(self, address: str) -> WalletChallenge:
+        """Request a signature challenge for the given Ethereum address.
+
+        No authentication required.
+        """
+        _validate_address(address)
+        data = self._http.post(
+            "/api/auth/wallet/challenge",
+            json={"address": address},
+            requires_auth=False,
+        )
+        return WalletChallenge(
+            challenge=data["challenge"],
+            expires_at=data["expiresAt"],
+        )
+
+    def verify(self, address: str, signature: str, challenge: str = "") -> WalletVerifyResult:
+        """Submit signed challenge to create account or login.
+
+        No authentication required. On success, JWT tokens are stored
+        for subsequent authenticated requests.
+
+        Args:
+            address: Ethereum address (0x-prefixed, 40 hex chars)
+            signature: EIP-191 signature of the challenge message
+            challenge: Optional challenge string (server looks up internally)
+        """
+        _validate_address(address)
+        _validate_signature(signature)
+        body: dict = {"address": address, "signature": signature}
+        if challenge:
+            body["challenge"] = challenge
+        data = self._http.post(
+            "/api/auth/wallet/verify",
+            json=body,
+            requires_auth=False,
+        )
+        result = _parse_verify_result(data)
+        if result.token and result.refresh_token:
+            self._tokens.set_tokens(result.token, result.refresh_token)
+        return result
+
+    def link(self, address: str, signature: str, challenge: str = "") -> WalletLinkResult:
+        """Link an Ethereum wallet to the current account.
+
+        Requires JWT authentication.
+        """
+        _validate_address(address)
+        _validate_signature(signature)
+        body: dict = {"address": address, "signature": signature}
+        if challenge:
+            body["challenge"] = challenge
+        data = self._http.post(
+            "/api/auth/wallet/link",
+            json=body,
+        )
+        return WalletLinkResult(
+            success=data.get("success", False),
+            wallet_address=data.get("walletAddress", ""),
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncWalletAuthResource:
+    """Asynchronous wallet-based authentication operations."""
+
+    def __init__(self, http: AsyncHttpClient, tokens: AsyncTokenManager) -> None:
+        self._http = http
+        self._tokens = tokens
+
+    async def challenge(self, address: str) -> WalletChallenge:
+        """Request a signature challenge (no auth required)."""
+        _validate_address(address)
+        data = await self._http.post(
+            "/api/auth/wallet/challenge",
+            json={"address": address},
+            requires_auth=False,
+        )
+        return WalletChallenge(
+            challenge=data["challenge"],
+            expires_at=data["expiresAt"],
+        )
+
+    async def verify(self, address: str, signature: str, challenge: str = "") -> WalletVerifyResult:
+        """Submit signed challenge to create account or login (no auth required)."""
+        _validate_address(address)
+        _validate_signature(signature)
+        body: dict = {"address": address, "signature": signature}
+        if challenge:
+            body["challenge"] = challenge
+        data = await self._http.post(
+            "/api/auth/wallet/verify",
+            json=body,
+            requires_auth=False,
+        )
+        result = _parse_verify_result(data)
+        if result.token and result.refresh_token:
+            self._tokens.set_tokens(result.token, result.refresh_token)
+        return result
+
+    async def link(self, address: str, signature: str, challenge: str = "") -> WalletLinkResult:
+        """Link an Ethereum wallet to the current account (requires auth)."""
+        _validate_address(address)
+        _validate_signature(signature)
+        body: dict = {"address": address, "signature": signature}
+        if challenge:
+            body["challenge"] = challenge
+        data = await self._http.post(
+            "/api/auth/wallet/link",
+            json=body,
+        )
+        return WalletLinkResult(
+            success=data.get("success", False),
+            wallet_address=data.get("walletAddress", ""),
+        )