s-librarykit 0.5.2__tar.gz → 0.5.4__tar.gz

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s-librarykit
-Version: 0.5.2
+Version: 0.5.4
 Summary: Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов.
 Author: Dmitry
 License: MIT

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/librarykit/__init__.py

@@ -220,6 +220,7 @@ from librarykit.retry import (
 # reference (`WebSocketsStreamTransport`) тянет extra [ws] lazy ВНУТРИ конструктора,
 # поэтому реэкспорт безопасен — `import librarykit` без extra не падает.
 from librarykit.rpc import JsonCodec, PrefixedJsonCodec, RpcClient
+from librarykit.secret import Secret, mask_secrets_json
 from librarykit.secret_store import SecretStore
 
 # session_paths — единый резолвер путей браузерных сессий (~/.sessions): общая
@@ -236,6 +237,7 @@ from librarykit.sessions import (
     KekUnavailableError,
     SessionStore,
     SessionStoreError,
+    ensure_kek,
     resolve_kek,
 )
 from librarykit.stream import (
@@ -365,7 +367,10 @@ __all__ = [
     "SessionStoreError",
     "KekUnavailableError",
     "resolve_kek",
+    "ensure_kek",
     "SecretStore",
+    "Secret",
+    "mask_secrets_json",
     # errors + errmap: единая иерархия ERROR-HUB + карта ответ→ошибка
     "CliError",
     "ApiError",

s_librarykit-0.5.4/librarykit/browser/_cdp_state.py

@@ -0,0 +1,43 @@
+"""Общие хелперы снятия storage_state для CDP-семьи (nodriver-backend + capture-тап).
+
+`NodriverBackend.state_context()` и `capture_tap._CdpAdapter.storage_state()` оба снимают
+сессию из nodriver `Tab` по CDP — общая логика (нормализация sameSite + чтение localStorage
+активной вкладки в Playwright-форму origins) живёт здесь, чтобы не расходиться.
+"""
+from __future__ import annotations
+
+import json as _json
+from typing import Any
+
+_SAME_SITE_MAP = {"strict": "Strict", "lax": "Lax", "none": "None", "no_restriction": "None"}
+
+
+def normalize_samesite(value: Any) -> str | None:
+    """CDP/nodriver same_site → Playwright-форма ('Strict'|'Lax'|'None'). None — опустить поле."""
+    if value is None:
+        return None
+    return _SAME_SITE_MAP.get(str(getattr(value, "value", value)).strip().lower())
+
+
+async def read_origins(tab: Any) -> list[dict[str, Any]]:
+    """localStorage ТЕКУЩЕГО origin активной вкладки → origins-список Playwright storage_state.
+
+    nodriver видит только активную вкладку (нет мульти-origin снимка, как у Playwright
+    context.storage_state) — best-effort; about:blank / ошибки evaluate → пустой список.
+    """
+    try:
+        origin = await tab.evaluate("location.origin")
+        raw = await tab.evaluate("JSON.stringify(Object.entries(window.localStorage))")
+    except Exception:
+        return []
+    if not origin or origin == "null" or not isinstance(raw, str):
+        return []
+    try:
+        entries = _json.loads(raw)
+    except (ValueError, TypeError):
+        return []
+    ls = [{"name": k, "value": v} for k, v in entries]
+    return [{"origin": origin, "localStorage": ls}] if ls else []
+
+
+__all__ = ["normalize_samesite", "read_origins"]

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/librarykit/browser/capture_tap.py

@@ -525,20 +525,26 @@ class _CdpAdapter(_BaseAdapter):
         self._spawn(self._emit(self._h.on_action, NormalizedAction(raw=payload)))
 
     async def storage_state(self) -> dict[str, Any]:
+        from ._cdp_state import normalize_samesite, read_origins
+
         try:
             raw = await self._tab.send(self._cdp.storage.get_cookies())
         except Exception:
             return {"cookies": [], "origins": []}
         cookies = []
         for c in raw or []:
-            cookies.append({
+            ck = {
                 "name": c.name, "value": c.value, "domain": getattr(c, "domain", ""),
                 "path": getattr(c, "path", "/"), "expires": float(getattr(c, "expires", -1) or -1),
                 "httpOnly": bool(getattr(c, "http_only", False)),
                 "secure": bool(getattr(c, "secure", False)),
-                "sameSite": (getattr(getattr(c, "same_site", None), "value", None) or "Lax"),
-            })
-        return {"cookies": cookies, "origins": []}
+            }
+            same = normalize_samesite(getattr(c, "same_site", None))
+            if same is not None:
+                ck["sameSite"] = same
+            cookies.append(ck)
+        # origins с localStorage текущей вкладки (паритет с _NodriverStateContext).
+        return {"cookies": cookies, "origins": await read_origins(self._tab)}
 
     async def detach(self) -> None:
         await self._drain()

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/librarykit/browser/nodriver.py

@@ -126,13 +126,31 @@ class NodriverBackend:
         )
         out: list[dict[str, Any]] = []
         for c in raw or []:
+            same = getattr(c, "same_site", getattr(c, "sameSite", None))
             out.append({
                 "name": c.name, "value": c.value, "domain": getattr(c, "domain", ""),
                 "path": getattr(c, "path", "/"), "expires": getattr(c, "expires", -1),
                 "secure": getattr(c, "secure", False),
+                # http_only/same_site — для паритета storage_state (см. state_context).
+                "http_only": getattr(c, "http_only", getattr(c, "httpOnly", False)),
+                "same_site": str(getattr(same, "value", same)) if same is not None else None,
             })
         return out
 
+    def state_context(self) -> "_NodriverStateContext":
+        """Playwright-`BrowserContext`-совместимый шов над этим backend'ом.
+
+        Даёт `.cookies()` (в Playwright-форме) и `.storage_state(path=)`, поэтому
+        generic-каскад `state.py` (`save_storage_state` / `wait_required_cookies` /
+        `warm_or_autologin`) работает на nodriver ТАК ЖЕ, как на Playwright-семье —
+        паритет извлечения сессии (см. `feedback-nodriver-default-engine`):
+
+            from librarykit.browser import save_storage_state
+            await save_storage_state(backend.state_context(), path,
+                                     required_cookies={"__Secure-1PSID"})
+        """
+        return _NodriverStateContext(self)
+
     async def fetch(
         self,
         method: str,
@@ -176,3 +194,59 @@ class NodriverBackend:
 
     async def __aexit__(self, *exc: object) -> None:
         await self.aclose()
+
+
+# --------------------------------------------------------------------------- #
+# Паритет извлечения сессии: Playwright-context-совместимый шов над nodriver     #
+# --------------------------------------------------------------------------- #
+# Общая логика (sameSite + localStorage-origins) — в `_cdp_state`, чтобы не
+# расходиться с capture-тапом `_CdpAdapter`. Имя `_normalize_samesite` сохранено
+# как алиас (обратная совместимость публичного теста).
+from ._cdp_state import normalize_samesite as _normalize_samesite  # noqa: E402
+from ._cdp_state import read_origins as _read_origins  # noqa: E402
+
+
+def _pw_cookie(c: Mapping[str, Any]) -> dict[str, Any]:
+    """nodriver-cookie (из `NodriverBackend.cookies()`) → Playwright storage_state-форма."""
+    exp = c.get("expires")
+    ck: dict[str, Any] = {
+        "name": c["name"], "value": c["value"],
+        "domain": c.get("domain") or "", "path": c.get("path") or "/",
+        "expires": float(exp) if exp is not None else -1.0,
+        "httpOnly": bool(c.get("http_only", False)),
+        "secure": bool(c.get("secure", False)),
+    }
+    same = _normalize_samesite(c.get("same_site"))
+    if same is not None:
+        ck["sameSite"] = same
+    return ck
+
+
+class _NodriverStateContext:
+    """Мини-адаптер: presentует nodriver-сессию как Playwright `BrowserContext`.
+
+    Реализует ровно то, на что duck-typed `state.py`: `cookies()` (Playwright-форма) и
+    `storage_state(path=)` (`{cookies, origins}` c localStorage текущего origin). Ничего
+    больше — это шов совместимости, не полный BrowserContext.
+    """
+
+    def __init__(self, backend: NodriverBackend) -> None:
+        self._b = backend
+
+    async def cookies(self) -> list[dict[str, Any]]:
+        return [_pw_cookie(c) for c in await self._b.cookies()]
+
+    async def storage_state(self, path: str | Path | None = None) -> dict[str, Any]:
+        """Собрать `{cookies, origins}`; при заданном `path` — атомарно записать JSON."""
+        state = {"cookies": await self.cookies(), "origins": await self._origins()}
+        if path is not None:
+            target = Path(path)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            tmp = target.with_suffix(target.suffix + ".tmp")
+            tmp.write_text(_json.dumps(state), encoding="utf-8")
+            tmp.replace(target)
+        return state
+
+    async def _origins(self) -> list[dict[str, Any]]:
+        """localStorage ТЕКУЩЕГО origin (nodriver видит только активную вкладку). Best-effort."""
+        return await _read_origins(await self._b._ensure())  # noqa: SLF001 — свой же backend

s_librarykit-0.5.4/librarykit/secret.py

@@ -0,0 +1,66 @@
+"""Secret — неутекаемый секрет: маска в repr/str/json, сырое только через .reveal().
+
+НЕ subclass str: обёртка форсит явный .reveal() в точке использования (сборка httpx-
+заголовка), поэтому секрет нельзя случайно склеить в URL/f-string/лог. Стандарт для
+всех секрет-полей (Account.key, credential-токены, …) — новое поле оборачивается в
+Secret и получает маскирование даром.
+"""
+from __future__ import annotations
+
+import hmac
+from typing import Any
+
+_MASK = "Secret(***)"
+
+
+class Secret:
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str | "Secret") -> None:
+        self._value = value._value if isinstance(value, Secret) else value
+
+    def reveal(self) -> str:
+        """Сырое значение — только в точке использования (заголовок/аутентификация)."""
+        return self._value
+
+    @classmethod
+    def wrap(cls, value: "str | Secret | None") -> "Secret | None":
+        """Идемпотентно обернуть строку в Secret (None → None, Secret → как есть)."""
+        if value is None:
+            return None
+        return value if isinstance(value, cls) else cls(value)
+
+    def __repr__(self) -> str:
+        return _MASK
+
+    def __str__(self) -> str:
+        return _MASK
+
+    def __format__(self, spec: str) -> str:
+        return _MASK
+
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __len__(self) -> int:
+        return len(self._value)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Secret):
+            return hmac.compare_digest(self._value, other._value)
+        if isinstance(other, str):
+            return hmac.compare_digest(self._value, other)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._value)  # для frozen-dataclass; hash необратим — не утечка
+
+
+def mask_secrets_json(obj: Any) -> Any:
+    """`default=` для json.dumps: Secret → маска. Прочее — TypeError (стандартно)."""
+    if isinstance(obj, Secret):
+        return "***"
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+__all__ = ["Secret", "mask_secrets_json"]

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/librarykit/sessions/__init__.py

@@ -237,6 +237,32 @@ def resolve_kek(*, allow_prompt: bool = True) -> bytes | None:
     return None
 
 
+def ensure_kek() -> bytes:
+    """Гарантировать KEK: вернуть существующий или создать+записать в OS keyring.
+
+    Если KEK уже резолвится (keyring/env) — вернуть его. Иначе сгенерировать 32-байтный
+    ключ (Fernet.generate_key → urlsafe base64), записать в keyring ``librarykit/dek`` и
+    вернуть. Keyring недоступен → ``SessionStoreError`` (никакого молчаливого plaintext).
+    """
+    existing = resolve_kek(allow_prompt=False)
+    if existing is not None:
+        return existing
+    try:
+        import keyring
+    except Exception as exc:  # noqa: BLE001
+        raise SessionStoreError(
+            "keyring недоступен: невозможно создать KEK для шифрования секретов. "
+            "Установите keyring или задайте LIBRARYKIT_MASTER_KEY."
+        ) from exc
+    if keyring is None:  # тесты/окружение без бэкенда
+        raise SessionStoreError("keyring недоступен: невозможно создать KEK.")
+    from cryptography.fernet import Fernet
+
+    raw = Fernet.generate_key().decode("ascii")  # urlsafe-base64 от 32 байт
+    keyring.set_password(KEYRING_SERVICE, KEYRING_KEK_USER, raw)
+    return _coerce_kek(raw)
+
+
 # --------------------------------------------------------------------------- #
 # Криптопровайдер: DEK обёрнут KEK; storage_state шифруется DEK-ом            #
 # --------------------------------------------------------------------------- #

{s_librarykit-0.5.2 → s_librarykit-0.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s-librarykit"
-version = "0.5.2"
+version = "0.5.4"
 description = "Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов."
 readme = "README.md"
 license = { text = "MIT" }

s_librarykit-0.5.4/tests/test_cdp_state.py

@@ -0,0 +1,58 @@
+"""Общие CDP-хелперы снятия storage_state (nodriver-backend + capture-тап)."""
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+from librarykit.browser._cdp_state import normalize_samesite, read_origins
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [("Strict", "Strict"), ("Lax", "Lax"), ("None", "None"),
+     ("no_restriction", "None"), ("garbage", None), (None, None)],
+)
+def test_normalize_samesite(raw, expected):
+    assert normalize_samesite(raw) == expected
+
+
+def test_normalize_samesite_enum_like():
+    class _E:
+        value = "Strict"
+    assert normalize_samesite(_E()) == "Strict"
+
+
+class _FakeTab:
+    def __init__(self, origin="https://x.example", ls=None, raises=False):
+        self._origin = origin
+        self._ls = ls or {}
+        self._raises = raises
+
+    async def evaluate(self, js, **_):
+        if self._raises:
+            raise RuntimeError("evaluate недоступен")
+        if "location.origin" in js:
+            return self._origin
+        if "localStorage" in js:
+            return json.dumps(list(self._ls.items()))
+        raise AssertionError(js)
+
+
+def test_read_origins_with_localstorage():
+    got = asyncio.run(read_origins(_FakeTab(origin="https://svc", ls={"a": "1", "b": "2"})))
+    assert got == [{"origin": "https://svc",
+                    "localStorage": [{"name": "a", "value": "1"}, {"name": "b", "value": "2"}]}]
+
+
+def test_read_origins_empty_localstorage():
+    assert asyncio.run(read_origins(_FakeTab(ls={}))) == []
+
+
+def test_read_origins_blank_origin():
+    assert asyncio.run(read_origins(_FakeTab(origin="null", ls={"a": "1"}))) == []
+
+
+def test_read_origins_evaluate_error_is_swallowed():
+    assert asyncio.run(read_origins(_FakeTab(raises=True))) == []

s_librarykit-0.5.4/tests/test_ensure_kek.py

@@ -0,0 +1,34 @@
+import base64
+import sys
+
+import pytest
+
+import librarykit.sessions as S
+from librarykit import ensure_kek
+
+
+def test_returns_existing_kek(monkeypatch):
+    existing = base64.urlsafe_b64decode(base64.urlsafe_b64encode(b"0" * 32))
+    monkeypatch.setattr(S, "resolve_kek", lambda **kw: existing)
+    assert ensure_kek() == existing and len(ensure_kek()) == 32
+
+
+def test_creates_and_persists_when_absent(monkeypatch):
+    monkeypatch.setattr(S, "resolve_kek", lambda **kw: None)
+    saved = {}
+
+    class _KR:
+        def set_password(self, service, user, value):
+            saved[(service, user)] = value
+
+    monkeypatch.setitem(sys.modules, "keyring", _KR())
+    kek = ensure_kek()
+    assert len(kek) == 32
+    assert (S.KEYRING_SERVICE, S.KEYRING_KEK_USER) in saved  # записан в keyring
+
+
+def test_raises_when_keyring_unavailable(monkeypatch):
+    monkeypatch.setattr(S, "resolve_kek", lambda **kw: None)
+    monkeypatch.setitem(sys.modules, "keyring", None)
+    with pytest.raises(S.SessionStoreError):
+        ensure_kek()  # нет keyring → громкая ошибка, не plaintext

s_librarykit-0.5.4/tests/test_nodriver_state_context.py

@@ -0,0 +1,127 @@
+"""Паритет извлечения сессии для nodriver: _NodriverStateContext + state.py-каскад.
+
+Без реального nodriver (опциональный extra) — через duck-typed фейк-backend, т.к.
+_NodriverStateContext зовёт лишь `backend.cookies()` + `backend._ensure()`.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+from librarykit.browser.nodriver import (
+    _NodriverStateContext,
+    _normalize_samesite,
+    _pw_cookie,
+)
+from librarykit.browser.state import (
+    load_cookies_dict,
+    save_storage_state,
+    wait_required_cookies,
+)
+
+
+class _FakeTab:
+    def __init__(self, origin="https://x.example", local_storage=None):
+        self._origin = origin
+        self._ls = local_storage or {}
+
+    async def evaluate(self, js, **_):
+        if "location.origin" in js:
+            return self._origin
+        if "localStorage" in js:
+            return json.dumps(list(self._ls.items()))
+        raise AssertionError(f"неожиданный evaluate: {js}")
+
+
+class _FakeBackend:
+    """Duck-typed под то, что реально дёргает _NodriverStateContext."""
+
+    def __init__(self, cookies, tab=None):
+        self._cookies = cookies
+        self._tab = tab or _FakeTab()
+
+    async def cookies(self):
+        return list(self._cookies)
+
+    async def _ensure(self):
+        return self._tab
+
+
+def _nd_cookie(name, value, **kw):
+    base = {
+        "name": name, "value": value, "domain": "x.example", "path": "/",
+        "expires": -1, "secure": True, "http_only": True, "same_site": "Lax",
+    }
+    base.update(kw)
+    return base
+
+
+# --- pure helpers --------------------------------------------------------- #
+@pytest.mark.parametrize(
+    "raw,expected",
+    [("Strict", "Strict"), ("Lax", "Lax"), ("None", "None"),
+     ("no_restriction", "None"), ("weird", None), (None, None)],
+)
+def test_normalize_samesite(raw, expected):
+    assert _normalize_samesite(raw) == expected
+
+
+def test_pw_cookie_maps_to_playwright_shape():
+    ck = _pw_cookie(_nd_cookie("sid", "v", expires=123.0))
+    assert ck["name"] == "sid" and ck["httpOnly"] is True and ck["secure"] is True
+    assert ck["sameSite"] == "Lax" and ck["expires"] == 123.0
+    assert "http_only" not in ck  # переименовано, не продублировано
+
+
+def test_pw_cookie_omits_samesite_when_unknown():
+    ck = _pw_cookie(_nd_cookie("sid", "v", same_site=None))
+    assert "sameSite" not in ck
+
+
+# --- adapter -------------------------------------------------------------- #
+def test_state_context_cookies_playwright_shape():
+    ctx = _NodriverStateContext(_FakeBackend([_nd_cookie("__Secure-1PSID", "x")]))
+    cookies = asyncio.run(ctx.cookies())
+    assert cookies[0]["name"] == "__Secure-1PSID" and cookies[0]["httpOnly"] is True
+
+
+def test_state_context_storage_state_dict_with_localstorage():
+    tab = _FakeTab(origin="https://gemini.google.com", local_storage={"k": "v"})
+    ctx = _NodriverStateContext(_FakeBackend([_nd_cookie("sid", "1")], tab=tab))
+    state = asyncio.run(ctx.storage_state())
+    assert state["cookies"][0]["name"] == "sid"
+    assert state["origins"] == [
+        {"origin": "https://gemini.google.com", "localStorage": [{"name": "k", "value": "v"}]}
+    ]
+
+
+def test_state_context_origins_empty_on_blank():
+    tab = _FakeTab(origin="null", local_storage={})
+    ctx = _NodriverStateContext(_FakeBackend([], tab=tab))
+    assert asyncio.run(ctx.storage_state())["origins"] == []
+
+
+# --- интеграция со state.py-каскадом (тот же путь, что у Playwright-семьи) --- #
+def test_save_storage_state_via_adapter(tmp_path):
+    ctx = _NodriverStateContext(_FakeBackend([_nd_cookie("__Secure-1PSID", "tok")]))
+    out = tmp_path / "sess" / "storage_state.json"
+    saved = asyncio.run(save_storage_state(ctx, out, required_cookies={"__Secure-1PSID"}))
+    assert saved.is_file()
+    assert load_cookies_dict(saved) == {"__Secure-1PSID": "tok"}  # плоский для httpx
+
+
+def test_save_storage_state_raises_when_required_missing(tmp_path):
+    ctx = _NodriverStateContext(_FakeBackend([_nd_cookie("other", "1")]))
+    with pytest.raises(TimeoutError):
+        asyncio.run(save_storage_state(
+            ctx, tmp_path / "s.json",
+            required_cookies={"__Secure-1PSID"}, timeout_sec=0.05,
+        ))
+
+
+def test_wait_required_cookies_on_adapter():
+    ctx = _NodriverStateContext(_FakeBackend([_nd_cookie("a", "1"), _nd_cookie("b", "2")]))
+    assert asyncio.run(wait_required_cookies(ctx, {"a", "b"})) is True
+    assert asyncio.run(wait_required_cookies(ctx, {"a", "missing"}, timeout_sec=0.05)) is False

s_librarykit-0.5.4/tests/test_secret.py

@@ -0,0 +1,43 @@
+import json
+
+import pytest
+
+from librarykit import Secret, mask_secrets_json
+
+
+def test_masks_in_repr_str_format():
+    s = Secret("sk-supersecret-123")
+    assert repr(s) == "Secret(***)"
+    assert str(s) == "Secret(***)"
+    assert f"{s}" == "Secret(***)"
+    assert "supersecret" not in repr(s) + str(s) + f"{s}"
+
+
+def test_reveal_returns_raw():
+    assert Secret("tok-42").reveal() == "tok-42"
+
+
+def test_not_str_subclass():
+    assert not isinstance(Secret("x"), str)  # нельзя молча склеить в URL/f-string
+
+
+def test_bool_and_len_without_reveal():
+    assert bool(Secret("x")) is True and bool(Secret("")) is False
+    assert len(Secret("abcd")) == 4
+
+
+def test_eq_constant_time_and_wrap_idempotent():
+    assert Secret("a") == Secret("a")
+    assert Secret("a") == "a"
+    assert Secret("a") != Secret("b")
+    inner = Secret("z")
+    assert Secret(inner).reveal() == "z"          # обёртка Secret(Secret) не двоится
+    assert Secret.wrap(None) is None
+    assert Secret.wrap("q").reveal() == "q"
+    assert Secret.wrap(inner) is inner            # уже Secret → как есть
+
+
+def test_json_default_masks_and_bare_dumps_raises():
+    assert json.dumps({"k": Secret("v")}, default=mask_secrets_json) == '{"k": "***"}'
+    with pytest.raises(TypeError):
+        json.dumps({"k": Secret("v")})            # без энкодера — громкий отказ, не молча