newapi-python 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

newapi/__init__.py

@@ -72,4 +72,4 @@ __all__ = [
     "ValidationError",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

newapi/_client.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import re
 import threading
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any, cast
 from urllib.parse import unquote, urlsplit, urlunsplit
 
@@ -33,6 +34,7 @@ from ._resources import (
     TokensResource,
     TopUpResource,
 )
+from ._session_blob import decode_session_blob
 
 _ERROR_TYPES: dict[int, type[APIError]] = {
     400: ValidationError,
@@ -46,6 +48,8 @@ _ERROR_TYPES: dict[int, type[APIError]] = {
 _LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
 _REFRESH_COOKIE = "new_api_refresh"
 _REFRESH_COOKIE_PATTERN = re.compile(rf"(?:^|[;,\s]){_REFRESH_COOKIE}=([^;\s]+)")
+_DEFAULT_SESSION_COOKIE = "session"
+_USER_ID_HEADER = "New-Api-User"
 _DEFAULT_QUOTA_PER_UNIT = 500000.0
 
 
@@ -145,6 +149,9 @@ class NewAPI:
         refresh_token: str | None = None,
         expires_at: float | None = None,
         session_id: str | None = None,
+        session_token: str | None = None,
+        user_id: int | None = None,
+        session_cookie: str = _DEFAULT_SESSION_COOKIE,
         timeout: float | tuple[float, float] = 30.0,
         language: str = "en",
         allow_insecure: bool = False,
@@ -153,11 +160,18 @@ class NewAPI:
     ) -> None:
         self.base_url = _api_base_url(base_url, allow_insecure)
         self.language = language
+        self._session_cookie = session_cookie
+        self._session_cookie_pattern = re.compile(
+            rf"(?:^|[;,\s]){re.escape(session_cookie)}=([^;\s]+)"
+        )
+        resolved_user_id = self._resolve_session_user_id(access_token, session_token, user_id)
         self._tokens = SessionTokens(
             access_token=access_token,
             refresh_token=refresh_token,
             expires_at=expires_at,
             session_id=session_id,
+            session_token=session_token,
+            user_id=resolved_user_id,
         )
         self._refresh_lock = threading.RLock()
         self._pending_2fa_token: str | None = None
@@ -196,6 +210,36 @@ class NewAPI:
     def quota_per_unit(self) -> float | None:
         return self._quota_per_unit
 
+    def _resolve_session_user_id(
+        self,
+        access_token: str | None,
+        session_token: str | None,
+        user_id: int | None,
+    ) -> int | None:
+        if access_token and session_token:
+            raise ConfigurationError("pass either access_token or session_token, not both")
+        if access_token and user_id is None:
+            raise ConfigurationError(
+                "user_id is required when authenticating with an access_token; "
+                "new-api instances reject such requests with 401 "
+                "'Unauthorized, New-Api-User header not provided'"
+            )
+        if not session_token or user_id is not None:
+            return user_id
+        try:
+            fields = decode_session_blob(session_token)
+        except ValueError as error:
+            raise ConfigurationError(
+                "session_token is not a decodable browser session cookie; "
+                "pass user_id alongside it for instances with opaque cookies"
+            ) from error
+        embedded_id = fields.get("id")
+        if not isinstance(embedded_id, int) or isinstance(embedded_id, bool):
+            raise ConfigurationError(
+                "session_token does not embed a user id; pass user_id explicitly"
+            )
+        return embedded_id
+
     def login(
         self,
         username: str,
@@ -255,6 +299,13 @@ class NewAPI:
         return user
 
     def refresh(self) -> SessionTokens:
+        if self._tokens.session_token and not self._tokens.refresh_token:
+            raise AuthenticationError(
+                "Session-cookie authentication has no refresh flow; "
+                "extract a fresh browser session cookie instead",
+                status_code=401,
+                code="SESSION_COOKIE_NO_REFRESH",
+            )
         with self._refresh_lock:
             refresh_token = self._tokens.refresh_token
             if not refresh_token:
@@ -284,8 +335,21 @@ class NewAPI:
                 raise
 
     def logout(self) -> None:
+        if self._tokens.session_token and not self._tokens.access_token:
+            try:
+                self._request(
+                    "POST",
+                    "user/logout",
+                    authenticated=True,
+                    allow_refresh=False,
+                )
+            finally:
+                self.clear_auth()
+            return
         refresh_token = self._tokens.refresh_token
         headers: dict[str, str] = {"Origin": self._origin()}
+        if self._tokens.user_id is not None:
+            headers[_USER_ID_HEADER] = str(self._tokens.user_id)
         if self._tokens.access_token:
             headers["Authorization"] = f"{self._tokens.token_type} {self._tokens.access_token}"
         try:
@@ -418,6 +482,8 @@ class NewAPI:
             authenticated=authenticated,
             refresh_cookie=refresh_cookie,
         )
+        if authenticated and self._tokens.session_token:
+            self._harvest_session_cookie(response)
         if (
             response.status_code == 401
             and authenticated
@@ -450,12 +516,17 @@ class NewAPI:
         request_headers = {
             "Accept": "application/json",
             "Accept-Language": self.language,
-            "User-Agent": "newapi-python/0.1.0",
+            "User-Agent": "newapi-python/0.3.0",
         }
-        if authenticated and self._tokens.access_token:
-            request_headers["Authorization"] = (
-                f"{self._tokens.token_type} {self._tokens.access_token}"
-            )
+        if authenticated:
+            if self._tokens.user_id is not None:
+                request_headers[_USER_ID_HEADER] = str(self._tokens.user_id)
+            if self._tokens.session_token:
+                request_headers["Cookie"] = f"{self._session_cookie}={self._tokens.session_token}"
+            elif self._tokens.access_token:
+                request_headers["Authorization"] = (
+                    f"{self._tokens.token_type} {self._tokens.access_token}"
+                )
         if refresh_cookie and not self._session_has_refresh_cookie():
             request_headers["Cookie"] = f"{_REFRESH_COOKIE}={refresh_cookie}"
         if headers:
@@ -555,6 +626,15 @@ class NewAPI:
                 return stored
         return None
 
+    def _harvest_session_cookie(self, response: Any) -> None:
+        for value in _set_cookie_values(response):
+            match = self._session_cookie_pattern.search(value)
+            if match:
+                rotated = match.group(1)
+                if rotated and rotated != self._tokens.session_token:
+                    self._tokens = replace(self._tokens, session_token=rotated)
+                return
+
     def _session_has_refresh_cookie(self) -> bool:
         jar = getattr(self._http, "cookies", None)
         if jar is None:
@@ -606,12 +686,19 @@ class NewAPI:
         if isinstance(session, Mapping):
             raw_session_id = session.get("sid")
             session_id = raw_session_id if isinstance(raw_session_id, str) else None
+        user_id = self._tokens.user_id
+        user_data = auth.get("user")
+        if isinstance(user_data, Mapping):
+            raw_user_id = user_data.get("id")
+            if isinstance(raw_user_id, int) and not isinstance(raw_user_id, bool):
+                user_id = raw_user_id
         return SessionTokens(
             access_token=str(auth["access_token"]),
             refresh_token=refresh_token,
             expires_at=expires_at,
             token_type=str(token_type) if token_type else "Bearer",
             session_id=session_id,
+            user_id=user_id,
         )
 
     def _resolve_quota_per_unit(self) -> float:

newapi/_models.py

@@ -225,10 +225,12 @@ class SessionTokens:
     expires_at: float | None = None
     token_type: str = "Bearer"
     session_id: str | None = field(default=None, repr=False)
+    session_token: str | None = field(default=None, repr=False)
+    user_id: int | None = None
 
     @property
     def authenticated(self) -> bool:
-        return bool(self.access_token)
+        return bool(self.access_token or self.session_token)
 
     @property
     def expires_in(self) -> float | None:

newapi/_session_blob.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import base64
+import binascii
+
+
+class _Reader:
+    def __init__(self, data: bytes) -> None:
+        self.data = data
+        self.pos = 0
+
+    def byte(self) -> int:
+        if self.pos >= len(self.data):
+            raise ValueError("truncated gob data")
+        value = self.data[self.pos]
+        self.pos += 1
+        return value
+
+    def uint(self) -> int:
+        first = self.byte()
+        if first < 0x80:
+            return first
+        count = 0x100 - first
+        if not 1 <= count <= 8:
+            raise ValueError("invalid gob uint length marker")
+        raw = self.raw(count)
+        return int.from_bytes(raw, "big")
+
+    def int_value(self) -> int:
+        value = self.uint()
+        if value & 1:
+            return ~(value >> 1)
+        return value >> 1
+
+    def raw(self, count: int) -> bytes:
+        if count < 0 or self.pos + count > len(self.data):
+            raise ValueError("truncated gob data")
+        raw = self.data[self.pos : self.pos + count]
+        self.pos += count
+        return raw
+
+
+_INTERFACE_TYPES = {
+    b"\x06": ("string", b"\x0c"),
+    b"\x03": ("int", b"\x04"),
+    b"\x04": ("bool", b"\x02"),
+}
+_ROOT_TYPE_ID = 64
+
+
+def _interface_value(reader: _Reader) -> object:
+    selector = reader.raw(1)
+    if selector not in _INTERFACE_TYPES:
+        raise ValueError("unsupported gob interface value type")
+    name, tag = _INTERFACE_TYPES[selector]
+    if reader.raw(len(name)) != name.encode() or reader.raw(1) != tag:
+        raise ValueError("unexpected gob interface type header")
+    chunk_length = reader.uint()
+    chunk = _Reader(reader.raw(chunk_length))
+    if chunk.byte() != 0x00:
+        raise ValueError("unexpected gob value chunk lead byte")
+    if name == "string":
+        value: object = chunk.raw(chunk.uint()).decode()
+    elif name == "int":
+        value = chunk.int_value()
+    else:
+        value = bool(chunk.uint())
+    if chunk.pos != len(chunk.data):
+        raise ValueError("trailing bytes in gob value chunk")
+    return value
+
+
+def _decode_gob_map(data: bytes) -> dict[str, object]:
+    reader = _Reader(data)
+    while reader.pos < len(reader.data):
+        message = _Reader(reader.raw(reader.uint()))
+        type_id = message.int_value()
+        if type_id < 0:
+            continue
+        if type_id != _ROOT_TYPE_ID:
+            raise ValueError(f"unexpected gob root type id {type_id}")
+        if message.byte() != 0x00:
+            raise ValueError("unexpected gob map lead byte")
+        result: dict[str, object] = {}
+        for _ in range(message.uint()):
+            key = _interface_value(message)
+            value = _interface_value(message)
+            if not isinstance(key, str):
+                raise ValueError("gob session map key is not a string")
+            result[key] = value
+        if message.pos != len(message.data):
+            raise ValueError("trailing bytes in gob value message")
+        return result
+    raise ValueError("gob stream contains no value message")
+
+
+def _base64_decode(value: str) -> bytes:
+    padded = value + "=" * (-len(value) % 4)
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except (binascii.Error, ValueError):
+        return base64.b64decode(padded)
+
+
+def decode_session_blob(token: str) -> dict[str, object]:
+    parts = _base64_decode(token.strip()).split(b"|", 2)
+    if len(parts) != 3 or not parts[0].isdigit():
+        raise ValueError("value is not a gorilla-style session cookie")
+    return _decode_gob_map(_base64_decode(parts[1].decode()))

{newapi_python-0.1.0.dist-info → newapi_python-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: newapi-python
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python client for the user-facing dashboard API of new-api instances
 Author: Eight Labs
 License-Expression: MIT
@@ -55,10 +55,13 @@ client = NewAPI(
     "https://newapi.example.com",
     access_token=os.environ["NEWAPI_ACCESS_TOKEN"],
     refresh_token=os.environ.get("NEWAPI_REFRESH_TOKEN"),
+    user_id=int(os.environ["NEWAPI_USER_ID"]),
 )
 ```
 
-Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known. Users can also generate a long-lived system access token from the dashboard and pass it as `access_token` alone; such tokens cannot refresh browser sessions.
+Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known.
+
+Users can also generate a long-lived system access token from the dashboard and pass it as `access_token`. Access-token authentication additionally requires `user_id`: new-api instances verify the numeric `New-Api-User` header on every authenticated request and reject requests without it with `401 Unauthorized, New-Api-User header not provided`. The client sends the header automatically from `user_id`, and `login()` and `refresh()` capture the id from the instance's responses. Such tokens cannot refresh browser sessions on their own.
 
 The default browser fingerprint is Chrome. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
 
@@ -69,6 +72,23 @@ session = requests.Session(impersonate="safari")
 client = NewAPI("https://newapi.example.com", session=session)
 ```
 
+## Authenticate with a browser session cookie
+
+One-api style deployments without the token-rotation flow authenticate the dashboard through the gorilla `session` cookie plus the numeric `New-Api-User` header that their frontend sends on every request. Pass the cookie value copied from the browser as `session_token`; the client decodes the embedded user id automatically and replays both the cookie and the header:
+
+```python
+import os
+
+from newapi import NewAPI
+
+client = NewAPI(
+    "https://oneapi.example.com",
+    session_token=os.environ["NEWAPI_SESSION_TOKEN"],
+)
+```
+
+Instances with opaque cookies embed no user id; pass `user_id` explicitly in that case, or to override the embedded one. The cookie name defaults to `session` and can be changed with `session_cookie`. When the instance re-issues the session cookie, the client picks up the rotated value from `Set-Cookie` automatically. Session-cookie mode has no refresh flow: `refresh()` raises `AuthenticationError`, and once the server-side session expires a fresh cookie value must be extracted from the browser. `logout()` calls the fork's legacy `POST /api/user/logout` endpoint in this mode.
+
 ## Log in with username and password
 
 ```python

newapi_python-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+newapi/__init__.py,sha256=_BZDS3mvNV8s4ckB4x4duVPa5QxruHLHxCeuS5gYc5I,1310
+newapi/_client.py,sha256=ci7AU9R0_IA_xx-Ev01xjv8NMdxgPoJr2dgrMu85zaI,25791
+newapi/_crypto.py,sha256=ocWpBUsQoZlg_dk1Q_vLVKLGEc6I80RpgYlHmLQXZ-I,3902
+newapi/_exceptions.py,sha256=YlZVzYf6VUKSN-fVVvFHfunoNJg6LLcuR2IdHNKzaCg,2049
+newapi/_models.py,sha256=FWUDMqjroiaZLZdj8v_CKcANB6XZZMULrXWdu5mrxE0,6379
+newapi/_resources.py,sha256=IQ1B3QoufC4p8KpXg6NlU9nmUQgTYmncSIYPLoLKYUc,28476
+newapi/_session_blob.py,sha256=GIv4k2H0YrPghNGRg8iY2LZ8kgkFLrlMCpvUtIy35kw,3547
+newapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+newapi_python-0.3.0.dist-info/METADATA,sha256=SFbWbiKQppLpy6HXcJ5uTuVVn-KGoV36wDLyjroxlro,11367
+newapi_python-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+newapi_python-0.3.0.dist-info/licenses/LICENSE,sha256=SIZvsDcR9_4_Q4IMiJNqUwZWvdAmwjRHlXIQkXFwCwE,1067
+newapi_python-0.3.0.dist-info/RECORD,,

newapi_python-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-newapi/__init__.py,sha256=RxmHlpJQCJ-vQhHsKT06x9ppedYms__-hx14SVf6m3A,1310
-newapi/_client.py,sha256=GFrcoTTXtE660jDk45JtVWLLjMfJkLfdl390IuZMul8,21925
-newapi/_crypto.py,sha256=ocWpBUsQoZlg_dk1Q_vLVKLGEc6I80RpgYlHmLQXZ-I,3902
-newapi/_exceptions.py,sha256=YlZVzYf6VUKSN-fVVvFHfunoNJg6LLcuR2IdHNKzaCg,2049
-newapi/_models.py,sha256=8hI47h4o5F5D3CuBEl491UvjEcC1qxCZgflEsuwFfx0,6262
-newapi/_resources.py,sha256=IQ1B3QoufC4p8KpXg6NlU9nmUQgTYmncSIYPLoLKYUc,28476
-newapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-newapi_python-0.1.0.dist-info/METADATA,sha256=DlRfbe3_knGRi2PppLNI5sGcsZ4Y0C_purpo7N2Zv7E,9776
-newapi_python-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-newapi_python-0.1.0.dist-info/licenses/LICENSE,sha256=SIZvsDcR9_4_Q4IMiJNqUwZWvdAmwjRHlXIQkXFwCwE,1067
-newapi_python-0.1.0.dist-info/RECORD,,