newapi-python 0.1.0__py3-none-any.whl

newapi/_crypto.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import re
+from collections.abc import Callable
+from typing import Any
+
+from ._exceptions import ProtocolError
+
+_PEM_STRIP = re.compile(r"-----BEGIN PUBLIC KEY-----|-----END PUBLIC KEY-----|\s")
+
+
+def _read_der(data: bytes, offset: int) -> tuple[int, bytes, int]:
+    if offset >= len(data):
+        raise ValueError("truncated DER")
+    tag = data[offset]
+    offset += 1
+    length = data[offset]
+    offset += 1
+    if length & 0x80:
+        size = length & 0x7F
+        if size == 0 or offset + size > len(data):
+            raise ValueError("invalid DER length")
+        length = int.from_bytes(data[offset : offset + size], "big")
+        offset += size
+    if length <= 0 or offset + length > len(data):
+        raise ValueError("invalid DER length")
+    return tag, data[offset : offset + length], offset + length
+
+
+def _read_sequence(data: bytes) -> bytes:
+    tag, value, _ = _read_der(data, 0)
+    if tag != 0x30:
+        raise ValueError("expected a DER sequence")
+    return value
+
+
+def _read_integer(data: bytes, offset: int) -> tuple[int, int]:
+    tag, value, end = _read_der(data, offset)
+    if tag != 0x02:
+        raise ValueError("expected a DER integer")
+    return int.from_bytes(value, "big"), end
+
+
+def _parse_spki_rsa_public_key(pem: str) -> tuple[int, int]:
+    body = _PEM_STRIP.sub("", pem)
+    try:
+        der = base64.b64decode(body, validate=True)
+        spki = _read_sequence(der)
+        tag, algorithm, offset = _read_der(spki, 0)
+        if tag != 0x30:
+            raise ValueError("expected an algorithm identifier sequence")
+        oid_tag, oid, _ = _read_der(algorithm, 0)
+        if oid_tag != 0x06 or oid != b"\x2a\x86\x48\x86\xf7\x0d\x01\x01\x01":
+            raise ValueError("not an RSA public key")
+        tag, key_bytes, _ = _read_der(spki, offset)
+        if tag != 0x03 or not key_bytes.startswith(b"\x00"):
+            raise ValueError("invalid subject public key bit string")
+        rsa_public = _read_sequence(key_bytes[1:])
+        modulus, offset = _read_integer(rsa_public, 0)
+        exponent, _ = _read_integer(rsa_public, offset)
+        if modulus < 3 or exponent < 3:
+            raise ValueError("invalid RSA parameters")
+        return modulus, exponent
+    except (ValueError, IndexError) as error:
+        raise ProtocolError(
+            f"instance returned an unusable password encryption key: {error}"
+        ) from error
+
+
+def _mgf1(seed: bytes, length: int, hash_func: Callable[[bytes], Any]) -> bytes:
+    output = bytearray()
+    counter = 0
+    while len(output) < length:
+        output.extend(hash_func(seed + counter.to_bytes(4, "big")).digest())
+        counter += 1
+    return bytes(output[:length])
+
+
+def rsa_oaep_sha256_encrypt(message: bytes, public_key_pem: str) -> str:
+    modulus, exponent = _parse_spki_rsa_public_key(public_key_pem)
+    key_size = (modulus.bit_length() + 7) // 8
+    hash_length = hashlib.sha256().digest_size
+    max_message = key_size - 2 * hash_length - 2
+    if len(message) > max_message:
+        raise ValueError("message is too long for the instance's password encryption key")
+    seed = os.urandom(hash_length)
+    padding_length = max_message - len(message)
+    label_hash = hashlib.sha256(b"").digest()
+    encoded = bytearray(b"\x00" + seed + label_hash + b"\x00" * padding_length + b"\x01" + message)
+    db_mask = _mgf1(seed, key_size - hash_length - 1, hashlib.sha256)
+    for index in range(key_size - hash_length - 1):
+        encoded[1 + hash_length + index] ^= db_mask[index]
+    seed_mask = _mgf1(bytes(encoded[1 + hash_length :]), hash_length, hashlib.sha256)
+    for index in range(hash_length):
+        encoded[1 + index] ^= seed_mask[index]
+    ciphertext = pow(int.from_bytes(bytes(encoded), "big"), exponent, modulus)
+    return base64.b64encode(ciphertext.to_bytes(key_size, "big")).decode()

newapi/_exceptions.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+
+class NewAPIError(Exception):
+    """Base exception for the package."""
+
+
+class ConfigurationError(NewAPIError, ValueError):
+    """Raised when client configuration is invalid or unsafe."""
+
+
+class TransportError(NewAPIError):
+    """Raised when the instance cannot be reached or times out."""
+
+
+class ProtocolError(NewAPIError):
+    """Raised when an instance returns an unsupported response shape."""
+
+
+class APIError(NewAPIError):
+    """An error returned by a new-api instance."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: int | str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        label = str(self.code or self.status_code)
+        return f"new-api request failed ({label}): {self.message}"
+
+
+class AuthenticationError(APIError):
+    """Raised when login or session authentication fails."""
+
+
+class PermissionDeniedError(APIError):
+    """Raised when the user cannot perform an operation."""
+
+
+class NotFoundError(APIError):
+    """Raised when a requested resource does not exist."""
+
+
+class ValidationError(APIError):
+    """Raised when the instance rejects request input."""
+
+
+class ConflictError(APIError):
+    """Raised when an operation conflicts with current server state."""
+
+
+class RateLimitError(APIError):
+    """Raised when the panel API rate limit is exceeded."""
+
+
+class TwoFactorRequired(AuthenticationError):
+    """Raised when login must be completed with a TOTP or backup code."""
+
+    def __init__(self, flow_token: str, expires_at: float | None = None) -> None:
+        super().__init__(
+            "Two-factor authentication is required",
+            status_code=401,
+            code="TWO_FACTOR_REQUIRED",
+        )
+        self.flow_token = flow_token
+        self.expires_at = expires_at

newapi/_models.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator, Mapping
+from copy import deepcopy
+from dataclasses import dataclass, field
+from decimal import Decimal
+from math import ceil
+from typing import Any, Generic, TypeVar
+
+_SENSITIVE_FIELDS = frozenset(
+    {
+        "access_token",
+        "allow_ips",
+        "authorization",
+        "cookie",
+        "encryption_key_id",
+        "flow_token",
+        "key",
+        "password",
+        "password_encrypted",
+        "refresh_token",
+        "secret",
+        "webhook_secret",
+        "webhook_url",
+    }
+)
+
+
+def _redacted(value: Any, field: str | None = None) -> Any:
+    if field is not None and field.lower() in _SENSITIVE_FIELDS and value not in (None, ""):
+        return "********"
+    if isinstance(value, Mapping):
+        return {str(key): _redacted(item, str(key)) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_redacted(item) for item in value]
+    return value
+
+
+def _wrapped(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return Resource(value)
+    if isinstance(value, list):
+        return [_wrapped(item) for item in value]
+    return value
+
+
+class Resource(Mapping[str, Any]):
+    """A response object supporting both mapping and attribute access."""
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: Mapping[str, Any]) -> None:
+        self._data = dict(data)
+
+    def __getitem__(self, key: str) -> Any:
+        return _wrapped(self._data[key])
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        if key in self._data:
+            return self[key]
+        return default
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({_redacted(self._data)!r})"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return an independent dictionary containing the full response data."""
+        return deepcopy(self._data)
+
+
+class User(Resource):
+    """The authenticated user's dashboard profile."""
+
+
+class Token(Resource):
+    """A user-owned gateway API token."""
+
+
+APIKey = Token
+
+
+class Log(Resource):
+    """One dashboard usage-log record."""
+
+
+UsageRecord = Log
+
+
+class TopUpOrder(Resource):
+    """A user balance-recharge order."""
+
+
+class Group(Resource):
+    """A group selectable by the authenticated user."""
+
+
+class SubscriptionPlan(Resource):
+    """A subscription plan available for purchase."""
+
+
+class Subscription(Resource):
+    """A user subscription entry."""
+
+
+class PaymentConfig(Resource):
+    """Payment availability and recharge configuration."""
+
+
+class PaymentLink(Resource):
+    """Checkout parameters returned after starting an online payment."""
+
+
+class LoginSession(Resource):
+    """A dashboard login session."""
+
+
+class Redemption(Resource):
+    """A redemption-code result."""
+
+
+class CheckinStatus(Resource):
+    """Check-in configuration and history for one month."""
+
+
+class CheckinResult(Resource):
+    """The result of one successful check-in."""
+
+
+class Announcement(Resource):
+    """A user-visible announcement payload."""
+
+
+T = TypeVar("T", bound=Resource)
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """One page returned by a list endpoint."""
+
+    items: tuple[T, ...]
+    total: int
+    page: int
+    page_size: int
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @property
+    def pages(self) -> int:
+        return ceil(self.total / self.page_size) if self.page_size else 0
+
+    @property
+    def has_next(self) -> bool:
+        return self.page * self.page_size < self.total
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any], item_type: type[T]) -> Page[T]:
+        raw_items = data.get("items", [])
+        if not isinstance(raw_items, list):
+            raise TypeError("paginated response items must be a list")
+        if any(not isinstance(item, Mapping) for item in raw_items):
+            raise TypeError("paginated response items must contain objects")
+        page_size = int(data.get("page_size", len(raw_items) or 1))
+        return cls(
+            items=tuple(item_type(item) for item in raw_items),
+            total=int(data.get("total", len(raw_items))),
+            page=int(data.get("page", 1)),
+            page_size=page_size,
+        )
+
+
+@dataclass(frozen=True)
+class Balance:
+    """The user's quota values and their currency equivalents."""
+
+    quota: int
+    used_quota: int
+    aff_quota: int
+    quota_per_unit: float
+
+    def _amount(self, value: int) -> Decimal:
+        unit = Decimal(str(self.quota_per_unit)) if self.quota_per_unit else Decimal(0)
+        if unit == 0:
+            return Decimal(0)
+        return Decimal(value) / unit
+
+    @property
+    def amount(self) -> Decimal:
+        return self._amount(self.quota)
+
+    @property
+    def used_amount(self) -> Decimal:
+        return self._amount(self.used_quota)
+
+    @property
+    def aff_amount(self) -> Decimal:
+        return self._amount(self.aff_quota)
+
+
+@dataclass(frozen=True)
+class SessionTokens:
+    """The current in-memory dashboard session credentials."""
+
+    access_token: str | None = field(default=None, repr=False)
+    refresh_token: str | None = field(default=None, repr=False)
+    expires_at: float | None = None
+    token_type: str = "Bearer"
+    session_id: str | None = field(default=None, repr=False)
+
+    @property
+    def authenticated(self) -> bool:
+        return bool(self.access_token)
+
+    @property
+    def expires_in(self) -> float | None:
+        if self.expires_at is None:
+            return None
+        return max(0.0, self.expires_at - time.time())
+
+    def needs_refresh(self, leeway: float = 30.0) -> bool:
+        return (
+            self.refresh_token is not None
+            and self.expires_at is not None
+            and self.expires_at <= time.time() + leeway
+        )