newapi-python 0.1.0__tar.gz → 0.2.0__tar.gz

{newapi_python-0.1.0 → newapi_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: newapi-python
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python client for the user-facing dashboard API of new-api instances
 Author: Eight Labs
 License-Expression: MIT
@@ -69,6 +69,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.1.0 → newapi_python-0.2.0}/README.md

@@ -39,6 +39,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.1.0 → newapi_python-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "newapi-python"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python client for the user-facing dashboard API of new-api instances"
 readme = "README.md"
 requires-python = ">=3.10"

{newapi_python-0.1.0 → newapi_python-0.2.0}/src/newapi/__init__.py

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

{newapi_python-0.1.0 → newapi_python-0.2.0}/src/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,30 @@ 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 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 +293,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,6 +329,17 @@ 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.access_token:
@@ -418,6 +474,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,9 +508,13 @@ class NewAPI:
         request_headers = {
             "Accept": "application/json",
             "Accept-Language": self.language,
-            "User-Agent": "newapi-python/0.1.0",
+            "User-Agent": "newapi-python/0.2.0",
         }
-        if authenticated and self._tokens.access_token:
+        if authenticated and self._tokens.session_token:
+            request_headers["Cookie"] = f"{self._session_cookie}={self._tokens.session_token}"
+            if self._tokens.user_id is not None:
+                request_headers[_USER_ID_HEADER] = str(self._tokens.user_id)
+        elif authenticated and self._tokens.access_token:
             request_headers["Authorization"] = (
                 f"{self._tokens.token_type} {self._tokens.access_token}"
             )
@@ -555,6 +617,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:

{newapi_python-0.1.0 → newapi_python-0.2.0}/src/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_python-0.2.0/src/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 → newapi_python-0.2.0}/tests/test_client.py

@@ -10,6 +10,7 @@ import pytest
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import padding, rsa
 from cryptography.hazmat.primitives.hashes import SHA256
+from test_session_blob import FIXTURE_NO_ID, FIXTURE_USER, wrapped_session_cookie
 
 from newapi import (
     APIError,
@@ -23,6 +24,7 @@ from newapi import (
     TwoFactorRequired,
 )
 from newapi._crypto import rsa_oaep_sha256_encrypt
+from newapi._session_blob import decode_session_blob
 
 
 class TestSession:
@@ -457,3 +459,129 @@ def test_balance_uses_status_quota_per_unit() -> None:
     assert str(balance.used_amount) == "0.75"
     assert str(balance.aff_amount) == "0.25"
     assert client.quota_per_unit == 1000.0
+
+
+def test_session_cookie_authenticates_with_cookie_and_user_id_header() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path.endswith("/user/self")
+        assert request.headers.get("cookie") == f"session={token}"
+        assert request.headers.get("New-Api-User") == "42"
+        assert "Authorization" not in request.headers
+        return envelope({"id": 42, "username": "fixture"})
+
+    client = NewAPI("https://example.test", session_token=token, session=TestSession(handler))
+
+    user = client.me()
+
+    assert user.id == 42
+    assert client.is_authenticated
+    assert client.session.session_token == token
+    assert client.session.user_id == 42
+    assert client.session.access_token is None
+
+
+def test_session_cookie_accepts_explicit_user_id_override() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers.get("New-Api-User") == "77"
+        return envelope({"id": 77})
+
+    client = NewAPI(
+        "https://example.test",
+        session_token=token,
+        user_id=77,
+        session=TestSession(handler),
+    )
+
+    assert client.me().id == 77
+    assert client.session.user_id == 77
+
+
+def test_session_token_conflicts_with_access_token() -> None:
+    with pytest.raises(ConfigurationError):
+        NewAPI(
+            "https://example.test",
+            access_token="access",
+            session_token=wrapped_session_cookie(FIXTURE_USER),
+        )
+
+
+def test_session_token_without_embedded_id_requires_user_id() -> None:
+    token = wrapped_session_cookie(FIXTURE_NO_ID)
+
+    with pytest.raises(ConfigurationError):
+        NewAPI("https://example.test", session_token=token)
+
+
+def test_undecodable_session_token_requires_user_id() -> None:
+    with pytest.raises(ConfigurationError):
+        NewAPI("https://example.test", session_token="opaque-cookie-value")
+
+
+def test_session_cookie_rotation_is_harvested() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+    calls: list[str | None] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request.headers.get("cookie"))
+        if len(calls) == 1:
+            return httpx.Response(
+                200,
+                json={"success": True, "message": "", "data": {"id": 42}},
+                headers={"set-cookie": "session=session-rotated; Path=/; HttpOnly"},
+            )
+        return envelope({"id": 42})
+
+    client = NewAPI("https://example.test", session_token=token, session=TestSession(handler))
+
+    client.me()
+    client.me()
+
+    assert calls == [f"session={token}", "session=session-rotated"]
+    assert client.session.session_token == "session-rotated"
+
+
+def test_session_cookie_refresh_raises_clear_error() -> None:
+    client = NewAPI(
+        "https://example.test",
+        session_token=wrapped_session_cookie(FIXTURE_USER),
+        session=TestSession(lambda request: envelope({})),
+    )
+
+    with pytest.raises(AuthenticationError) as caught:
+        client.refresh()
+
+    assert caught.value.code == "SESSION_COOKIE_NO_REFRESH"
+
+
+def test_session_cookie_logout_uses_legacy_endpoint_and_clears_auth() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path.endswith("/user/logout")
+        assert request.method == "POST"
+        assert request.headers.get("cookie") == f"session={token}"
+        assert request.headers.get("New-Api-User") == "42"
+        return envelope(None)
+
+    client = NewAPI("https://example.test", session_token=token, session=TestSession(handler))
+
+    client.logout()
+
+    assert not client.is_authenticated
+
+
+def test_session_cookie_is_redacted_from_representations() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+
+    client = NewAPI(
+        "https://example.test",
+        session_token=token,
+        session=TestSession(lambda request: envelope({})),
+    )
+
+    assert token not in repr(client.session)
+    assert decode_session_blob(client.session.session_token)["id"] == 42

newapi_python-0.2.0/tests/test_session_blob.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import base64
+
+import pytest
+
+from newapi._session_blob import decode_session_blob
+
+FIXTURE_USER = bytes.fromhex(
+    "0d7f040102ff8000011001100000ff90ff80000506737472696e670c060004726f6c6503696e74"
+    "0402000206737472696e670c08000673746174757303696e740402000206737472696e670c0700"
+    "0567726f757006737472696e670c09000764656661756c7406737472696e670c04000269640369"
+    "6e740402005406737472696e670c0a0008757365726e616d6506737472696e670c09000766697874"
+    "757265"
+)
+FIXTURE_NO_ID = bytes.fromhex(
+    "0d7f040102ff800001100110000026ff80000106737472696e670c0a0008757365726e616d6506"
+    "737472696e670c0600046e6f6964"
+)
+FIXTURE_MIXED = bytes.fromhex(
+    "0d7f040102ff8000011001100000ff83ff80000406737472696e670c070005636f756e7403696e74"
+    "040900f94000000000000206737472696e670c040002696403696e740402002106737472696e670c"
+    "0600046e6f746506737472696e670c1b0019206ec3a96761746966202620c3bc6ec3af636f646520"
+    "e29c9306737472696e670c060004666c616704626f6f6c02020000"
+)
+
+
+def wrapped_session_cookie(gob: bytes) -> str:
+    inner = base64.urlsafe_b64encode(gob).decode().rstrip("=")
+    raw = f"1788284860|{inner}|fixture-signature".encode()
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def test_decodes_typical_session_cookie() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER)
+
+    assert decode_session_blob(token) == {
+        "group": "default",
+        "id": 42,
+        "role": 1,
+        "status": 1,
+        "username": "fixture",
+    }
+
+
+def test_decodes_cookie_without_user_id() -> None:
+    assert decode_session_blob(wrapped_session_cookie(FIXTURE_NO_ID)) == {"username": "noid"}
+
+
+def test_decodes_negative_integers_large_integers_booleans_and_unicode() -> None:
+    assert decode_session_blob(wrapped_session_cookie(FIXTURE_MIXED)) == {
+        "count": 9007199254740993,
+        "flag": False,
+        "id": -17,
+        "note": " négatif & ünïcode ✓",
+    }
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "session-cookie-value",
+        base64.urlsafe_b64encode(b"no pipes here").decode(),
+        base64.urlsafe_b64encode(b"not-a-timestamp|AAAA|sig").decode(),
+        base64.urlsafe_b64encode(b"1788284860|!!!not-base64!!!|sig").decode(),
+    ],
+)
+def test_rejects_non_session_values(value: str) -> None:
+    with pytest.raises(ValueError):
+        decode_session_blob(value)
+
+
+def test_rejects_truncated_gob_payload() -> None:
+    token = wrapped_session_cookie(FIXTURE_USER[:24])
+
+    with pytest.raises(ValueError):
+        decode_session_blob(token)