pubkit 0.1.0__py3-none-any.whl

pubkit/core/adapter.py

@@ -0,0 +1,206 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The adapter contract, plus the two base classes that do the hard parts.
+
+Six methods is the entire surface a new platform has to implement. Everything
+painful — verified transport, anchor resolution, image insertion, fingerprint
+verification, rate limiting, retries — lives in the base classes, because those
+are exactly the things that went wrong the first time and nobody should have to
+rediscover them per platform.
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from .auth import CredentialError, SessionStore, TokenStore
+from .capabilities import Capabilities, PublishPlan
+from .ir import Document
+
+
+@dataclass
+class RemoteRef:
+    """Where a document lives on a platform before publication."""
+
+    id: str
+    url: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PublishedRef:
+    id: str
+    url: str
+    published_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class Fingerprint:
+    """A cheap, stable summary of remote state.
+
+    Compared after a reload to prove a mutation actually stuck. Editors lie:
+    a delete that visibly worked came back after a refresh, and DOM edits to
+    link hrefs never persisted at all (failures B3, B4).
+    """
+
+    words: int
+    headings: list[str]
+    images: int
+    links: int
+    markers: int = 0
+
+    def digest(self) -> str:
+        payload = f"{self.words}|{'|'.join(self.headings)}|{self.images}|{self.links}|{self.markers}"
+        return hashlib.blake2b(payload.encode(), digest_size=8).hexdigest()
+
+    def assert_matches(self, expected: Fingerprint, *, tolerance: float = 0.02) -> None:
+        problems = []
+        if expected.words and abs(self.words - expected.words) / expected.words > tolerance:
+            problems.append(f"words {self.words} vs expected {expected.words}")
+        if self.images != expected.images:
+            problems.append(f"images {self.images} vs expected {expected.images}")
+        if self.markers:
+            problems.append(f"{self.markers} unresolved marker(s) still present")
+        if expected.headings and self.headings[: len(expected.headings)] != expected.headings:
+            problems.append("heading list diverges")
+        if problems:
+            raise VerificationFailed("; ".join(problems))
+
+
+class VerificationFailed(RuntimeError):
+    """Remote state does not match what we pushed. Never publish past this."""
+
+
+class AdapterError(RuntimeError):
+    pass
+
+
+class NotRetryable(AdapterError):
+    """A failure that retrying cannot fix.
+
+    A missing credential is not a transient error. Backing off four times
+    before telling the user to run `pubkit auth login` wastes 30 seconds and
+    buries the one line that actually helps them.
+    """
+
+
+class RateLimited(AdapterError):
+    def __init__(self, retry_after: float) -> None:
+        super().__init__(f"rate limited, retry after {retry_after:.1f}s")
+        self.retry_after = retry_after
+
+
+@dataclass
+class Context:
+    """What an adapter is handed. Deliberately narrow.
+
+    An adapter gets credentials for its own platform and nothing else.
+    """
+
+    platform: str
+    tokens: TokenStore
+    sessions: SessionStore
+    dry_run: bool = False
+    confirm: bool = False
+    headless: bool = True
+    workdir: str = ".pubkit"
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    name: str
+    capabilities: Capabilities
+
+    async def authenticate(self, ctx: Context) -> None: ...
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef: ...
+    async def push_content(self, doc: Document, plan: PublishPlan, ref: RemoteRef, ctx: Context) -> None: ...
+    async def push_media(self, doc: Document, plan: PublishPlan, ref: RemoteRef, ctx: Context) -> None: ...
+    async def verify(self, doc: Document, plan: PublishPlan, ref: RemoteRef, ctx: Context) -> Fingerprint: ...
+    async def publish(self, doc: Document, ref: RemoteRef, ctx: Context) -> PublishedRef: ...
+
+
+# ---------------------------------------------------------------------------
+# rate limiting + retry, shared by every adapter
+# ---------------------------------------------------------------------------
+class TokenBucket:
+    def __init__(self, rate: float, burst: int) -> None:
+        self.rate, self.burst = rate, burst
+        self._tokens = float(burst)
+        self._last = time.monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self, n: int = 1) -> None:
+        async with self._lock:
+            while True:
+                now = time.monotonic()
+                self._tokens = min(self.burst, self._tokens + (now - self._last) * self.rate)
+                self._last = now
+                if self._tokens >= n:
+                    self._tokens -= n
+                    return
+                await asyncio.sleep((n - self._tokens) / self.rate)
+
+
+async def with_retry(fn, *, attempts: int = 4, base: float = 1.0, cap: float = 30.0, on_retry=None):
+    """Bounded exponential backoff with full jitter.
+
+    Full jitter rather than fixed backoff on purpose: when five platform legs
+    fail at once because a shared dependency blipped, synchronised retries make
+    it worse.
+    """
+    last: Exception | None = None
+    for attempt in range(attempts):
+        try:
+            return await fn()
+        except (NotRetryable, PermissionError, CredentialError):
+            raise
+        except RateLimited as exc:
+            delay = exc.retry_after
+        except AdapterError as exc:
+            last = exc
+            delay = min(cap, base * 2**attempt) * random.random()
+        except Exception as exc:  # noqa: BLE001 - adapters raise anything
+            last = exc
+            delay = min(cap, base * 2**attempt) * random.random()
+        else:  # pragma: no cover
+            break
+        if attempt == attempts - 1:
+            break
+        if on_retry:
+            on_retry(attempt, delay, last)
+        await asyncio.sleep(delay)
+    raise AdapterError(f"gave up after {attempts} attempts: {last}") from last
+
+
+class BaseAdapter:
+    """Shared plumbing. Adapters subclass either this or a browser/API base."""
+
+    name: str = "base"
+    capabilities: Capabilities = Capabilities()
+    #: Requests per second and burst, tuned per platform.
+    rate: float = 1.0
+    burst: int = 3
+
+    def __init__(self) -> None:
+        self.bucket = TokenBucket(self.rate, self.burst)
+
+    async def authenticate(self, ctx: Context) -> None:  # pragma: no cover - default
+        return None
+
+    async def push_media(self, doc, plan, ref, ctx) -> None:  # pragma: no cover - default
+        return None
+
+    def guard_publish(self, ctx: Context) -> None:
+        """Publishing is public and hard to undo (failure D3)."""
+        if ctx.dry_run:
+            raise AdapterError("refusing to publish during a dry run")
+        if not ctx.confirm:
+            raise AdapterError(
+                "publishing requires explicit confirmation: pass --confirm "
+                "(or set PUBKIT_CONFIRM=1 in CI)"
+            )

pubkit/core/anchors.py

@@ -0,0 +1,89 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Finding a place in a document you do not control.
+
+Rich-text editors normalise what you give them. A caption written as
+
+    Where 80 GB goes. The cores never run out - the memory does.
+
+came back from the editor as
+
+    Where 80 GB goes. The cores never run out — the memory does.
+
+—hair spaces around an em dash. Exact string equality failed, the anchor was
+not found, and one image out of fifteen silently did not get placed. Matching
+text against a live editor needs to be forgiving in exactly the ways editors
+are aggressive.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from difflib import SequenceMatcher
+
+_DASHES = dict.fromkeys(map(ord, "‐‑‒–—―−"), "-")
+_QUOTES = {
+    ord("‘"): "'", ord("’"): "'", ord("‚"): "'", ord("‛"): "'",
+    ord("“"): '"', ord("”"): '"', ord("„"): '"', ord("″"): '"',
+}
+_SPACES = dict.fromkeys(
+    map(ord, "            　"),
+    " ",
+)
+
+
+def normalise(s: str) -> str:
+    """Fold everything an editor is likely to have changed."""
+    s = unicodedata.normalize("NFKC", s)
+    s = s.translate(_SPACES).translate(_DASHES).translate(_QUOTES)
+    s = s.replace("​", "").replace("", "")
+    s = re.sub(r"\s*-\s*", " - ", s)
+    s = re.sub(r"\s+", " ", s)
+    return s.strip().casefold()
+
+
+def similarity(a: str, b: str) -> float:
+    return SequenceMatcher(None, normalise(a), normalise(b)).ratio()
+
+
+def find_anchor(
+    candidates: list[str],
+    target: str,
+    *,
+    floor: float = 0.82,
+    used: set[int] | None = None,
+) -> int:
+    """Locate `target` among `candidates`, returning an index or -1.
+
+    Three passes, cheapest first: exact-after-normalisation, prefix, then
+    fuzzy above `floor`. `used` lets a caller place several identical captions
+    without every one resolving to the first match.
+    """
+    used = used or set()
+    norm = [normalise(c) for c in candidates]
+    t = normalise(target)
+
+    for i, c in enumerate(norm):
+        if i not in used and c == t:
+            return i
+
+    if len(t) >= 16:
+        for i, c in enumerate(norm):
+            if i not in used and (c.startswith(t[:40]) or t.startswith(c[:40])):
+                return i
+
+    best, best_score = -1, floor
+    for i, c in enumerate(norm):
+        if i in used:
+            continue
+        score = SequenceMatcher(None, c, t).ratio()
+        if score > best_score:
+            best, best_score = i, score
+    return best
+
+
+class AnchorNotFound(LookupError):
+    def __init__(self, target: str, closest: str | None, score: float) -> None:
+        hint = f" closest was {closest!r} at {score:.2f}" if closest else ""
+        super().__init__(f"no anchor for {target[:60]!r}.{hint}")
+        self.target, self.closest, self.score = target, closest, score

pubkit/core/auth.py

@@ -0,0 +1,209 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Credentials.
+
+Design rule, and it is not negotiable: **pubkit never accepts a password.**
+
+For API platforms the user pastes a token once and it goes into the OS
+keychain. For browser platforms the user signs in themselves, in a real visible
+browser window, and pubkit persists only the resulting session state — which it
+encrypts, with the key in the keychain.
+
+This is not only a security posture. It is also the only thing that works:
+platforms increasingly gate login behind CAPTCHA, device confirmation and MFA,
+none of which an automation layer should be trying to get past.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+
+try:  # pragma: no cover - environment dependent
+    import keyring
+
+    _HAVE_KEYRING = True
+except Exception:  # pragma: no cover
+    keyring = None  # type: ignore[assignment]
+    _HAVE_KEYRING = False
+
+try:  # pragma: no cover - environment dependent
+    from cryptography.fernet import Fernet
+
+    _HAVE_FERNET = True
+except Exception:  # pragma: no cover
+    Fernet = None  # type: ignore[assignment]
+    _HAVE_FERNET = False
+
+SERVICE = "pubkit"
+
+
+class CredentialError(RuntimeError):
+    """Missing or unusable credentials. Never retried — see adapter.NotRetryable."""
+
+
+@dataclass
+class TokenStore:
+    """API tokens. Keychain first, encrypted vault as the CI fallback."""
+
+    vault_path: Path = Path(".pubkit/vault.json")
+    service: str = SERVICE
+
+    # ------------------------------------------------------------------ read
+    def get(self, platform: str, key: str = "token") -> str | None:
+        env = os.environ.get(f"PUBKIT_{platform.upper()}_{key.upper()}")
+        if env:
+            return env
+        if _HAVE_KEYRING:
+            try:
+                val = keyring.get_password(self.service, f"{platform}:{key}")
+                if val:
+                    return val
+            except Exception:
+                pass
+        return self._vault_get(platform, key)
+
+    def require(self, platform: str, key: str = "token") -> str:
+        val = self.get(platform, key)
+        if not val:
+            raise CredentialError(
+                f"no {key} for {platform}. Run `pubkit auth login {platform}`, "
+                f"or set PUBKIT_{platform.upper()}_{key.upper()}."
+            )
+        return val
+
+    # ----------------------------------------------------------------- write
+    def set(self, platform: str, value: str, key: str = "token") -> None:
+        if _HAVE_KEYRING:
+            try:
+                keyring.set_password(self.service, f"{platform}:{key}", value)
+                return
+            except Exception:
+                pass
+        self._vault_set(platform, key, value)
+
+    def delete(self, platform: str, key: str = "token") -> None:
+        if _HAVE_KEYRING:
+            try:
+                keyring.delete_password(self.service, f"{platform}:{key}")
+            except Exception:
+                pass
+        data = self._vault_read()
+        data.pop(f"{platform}:{key}", None)
+        self._vault_write(data)
+
+    # ----------------------------------------------------------------- vault
+    def _vault_key(self) -> bytes:
+        env = os.environ.get("PUBKIT_VAULT_KEY")
+        if env:
+            return env.encode()
+        if _HAVE_KEYRING:
+            k = keyring.get_password(self.service, "_vault_key")
+            if not k:
+                k = Fernet.generate_key().decode() if _HAVE_FERNET else base64.urlsafe_b64encode(secrets.token_bytes(32)).decode()
+                keyring.set_password(self.service, "_vault_key", k)
+            return k.encode()
+        raise CredentialError(
+            "no keychain and no PUBKIT_VAULT_KEY set; cannot encrypt the vault. "
+            "In CI, set PUBKIT_VAULT_KEY from your secret store."
+        )
+
+    def _vault_read(self) -> dict[str, str]:
+        if not self.vault_path.exists():
+            return {}
+        blob = self.vault_path.read_bytes()
+        if not _HAVE_FERNET:
+            raise CredentialError("cryptography is required to read the vault")
+        return json.loads(Fernet(self._vault_key()).decrypt(blob))
+
+    def _vault_write(self, data: dict[str, str]) -> None:
+        if not _HAVE_FERNET:
+            raise CredentialError("cryptography is required to write the vault")
+        self.vault_path.parent.mkdir(parents=True, exist_ok=True)
+        blob = Fernet(self._vault_key()).encrypt(json.dumps(data).encode())
+        self.vault_path.write_bytes(blob)
+        os.chmod(self.vault_path, 0o600)
+
+    def _vault_get(self, platform: str, key: str) -> str | None:
+        try:
+            return self._vault_read().get(f"{platform}:{key}")
+        except Exception:
+            return None
+
+    def _vault_set(self, platform: str, key: str, value: str) -> None:
+        data = self._vault_read()
+        data[f"{platform}:{key}"] = value
+        self._vault_write(data)
+
+
+@dataclass
+class SessionStore:
+    """Persisted Playwright `storage_state`, encrypted at rest.
+
+    The flow is deliberately human-in-the-loop:
+
+        pubkit auth login medium
+          → opens a real browser window at the platform's login page
+          → you sign in (password manager, MFA, whatever it takes)
+          → pubkit waits for the post-login URL, saves the session, closes
+
+    pubkit sees cookies, never credentials.
+    """
+
+    dir: Path = Path(".pubkit/sessions")
+    tokens: TokenStore = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        if self.tokens is None:
+            self.tokens = TokenStore()
+
+    def _path(self, platform: str) -> Path:
+        return self.dir / f"{platform}.session"
+
+    def exists(self, platform: str) -> bool:
+        return self._path(platform).exists()
+
+    def save(self, platform: str, storage_state: dict) -> None:
+        raw = json.dumps(storage_state).encode()
+        if _HAVE_FERNET:
+            raw = Fernet(self.tokens._vault_key()).encrypt(raw)
+        p = self._path(platform)
+        p.write_bytes(raw)
+        os.chmod(p, 0o600)
+
+    def load(self, platform: str) -> dict | None:
+        p = self._path(platform)
+        if not p.exists():
+            return None
+        raw = p.read_bytes()
+        if _HAVE_FERNET:
+            try:
+                raw = Fernet(self.tokens._vault_key()).decrypt(raw)
+            except Exception as exc:  # corrupted or key rotated
+                raise CredentialError(
+                    f"cannot decrypt the saved {platform} session; "
+                    f"run `pubkit auth login {platform}` again ({exc})"
+                ) from exc
+        return json.loads(raw)
+
+    def forget(self, platform: str) -> None:
+        self._path(platform).unlink(missing_ok=True)
+
+
+class RedactingFilter:
+    """Log filter that strips secrets by construction, not by discipline."""
+
+    def __init__(self, secrets_: list[str]) -> None:
+        self._secrets = [s for s in secrets_ if s and len(s) >= 8]
+
+    def filter(self, record) -> bool:  # pragma: no cover - trivial
+        msg = str(record.getMessage())
+        for s in self._secrets:
+            if s in msg:
+                record.msg = msg.replace(s, "***redacted***")
+                record.args = ()
+        return True