parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/config.py

@@ -0,0 +1,349 @@
+"""Config resolution.
+
+Resolution order, highest first:
+  1. explicit kwarg to the generated root client (`Reddit(api_key=...)`)
+  2. environment variable
+  3. credentials file (~/.config/parse/credentials)
+  4. baked-in default
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import tempfile
+import urllib.parse
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_BASE_URL = "https://api.parse.bot"
+CANONICAL_HOST = "api.parse.bot"
+_TRUSTED_HOSTS = frozenset({
+    "api.parse.bot",   # canonical production host (https); opt others in via PARSE_EXTRA_TRUSTED_HOSTS.
+    # Explicit allowlist, NOT `*.parse.bot` minus a denylist: fail-closed on unknown
+    # subdomains. Source of truth = backend k8s IngressRoutes; to add a future SDK-facing
+    # host, add it here (https-only, exact match — no wildcard).
+})
+# Opt-in escape hatch for staging/preview QA. Empty by default, so prod behavior
+# is UNCHANGED — a user must explicitly set PARSE_EXTRA_TRUSTED_HOSTS (comma- or
+# space-separated hostnames) to let the API key ride to those hosts. Still
+# https-only in _host_is_trusted (the key never travels plaintext to a non-loopback
+# host), so the worst a typo does is widen trust to another https host the user named.
+_EXTRA_TRUSTED_HOSTS_ENV = "PARSE_EXTRA_TRUSTED_HOSTS"
+CREDENTIALS_PATH = Path.home() / ".config" / "parse" / "credentials"
+
+
+def extra_trusted_hosts() -> frozenset:
+    """Hosts the user has explicitly opted into trusting via
+    ``PARSE_EXTRA_TRUSTED_HOSTS`` (comma/space separated). Lowercased and
+    trailing-dot-stripped to match ``_host_is_trusted``'s normalization. Empty
+    set when the env var is unset/blank — the fail-closed default.
+
+    Read fresh from the environment on every call (not cached at import) so a
+    test/monkeypatch toggling the env var takes effect, and so a long-lived
+    process picks up an env change without restart."""
+    raw = os.environ.get(_EXTRA_TRUSTED_HOSTS_ENV, "")
+    return frozenset(
+        h.strip().lower().rstrip(".")
+        for h in raw.replace(",", " ").split()
+        if h.strip()
+    )
+
+
+def _host_is_trusted(url: str) -> bool:
+    """SOLE arbiter of whether Config.api_key may be non-None for a base_url.
+
+    Package-internal by convention, but intentionally imported by runtime sink
+    code and tests so every key-bearing path shares this exact predicate.
+
+    Self-contained and fail-closed, so it is the FULL local invariant for a
+    hand-built Config too (not only resolve()'s output). Trusts a host ONLY when:
+      - it is ASCII (C5: the matched host then IS the host httpx connects to —
+        non-ASCII / IDNA-confusable hosts are rejected here, not normalized), AND
+      - the scheme is http(s) (C2: no ftp/file/gopher, even on loopback), AND
+      - it is the canonical host over https, OR a user-opted-in extra host over
+        https (PARSE_EXTRA_TRUSTED_HOSTS — empty by default), OR syntactic loopback.
+    Pure function over urlsplit().hostname — NO DNS.
+
+    Invariant (corrected, C5): when this returns True, the ASCII host it matched
+    denotes the SAME DNS host httpx connects to (verified across case-fold /
+    trailing-dot / userinfo). This is NOT a byte-identity claim over all inputs —
+    a non-ASCII host is rejected here while httpx would IDNA-normalize it; that is
+    the safe (withhold) direction.
+    """
+    try:
+        parts = urllib.parse.urlsplit(url)
+        host = parts.hostname              # None for malformed authority; already lowercased
+    except ValueError:
+        # urlsplit() (and .hostname) raise ValueError on a malformed bracketed
+        # IPv6 authority (e.g. "http://[fe80::1"). This predicate is the sole,
+        # self-contained trust arbiter — it must be TOTAL and fail closed
+        # (return False), never raise an exception its four call sites
+        # (resolve / require_key / _request / save_credentials) don't expect.
+        return False
+    if host is None:
+        return False
+    if not host.isascii():                 # C5: reject confusables; keep gate-host == httpx-host
+        return False
+    if host.endswith("."):                 # root-anchored FQDN == same DNS host
+        host = host[:-1]
+    if parts.scheme not in ("http", "https"):   # C2: no non-http(s), even on loopback
+        return False
+    if parts.scheme == "https" and host in _TRUSTED_HOSTS:
+        return True
+    if parts.scheme == "https" and host in extra_trusted_hosts():
+        # User-opted-in staging/preview host (PARSE_EXTRA_TRUSTED_HOSTS).
+        # https-only — same plaintext-leak guard as the canonical host.
+        return True
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback   # 127.0.0.0/8, ::1
+    except ValueError:
+        return False                       # a name (incl. 127.0.0.1.evil.tld) is not loopback
+
+
+def _validate_base_url(url: str) -> str:
+    """Structurally validate a resolved base_url before the API key is attached
+    to requests against it.
+
+    The X-API-Key header is sent on every sync/runtime call to this host, so a
+    base_url sourced from env/credentials-file/--base-url must at least be a
+    real http(s) URL with a host and no embedded credentials. We deliberately do
+    NOT mandate https: the suite and local proxies use ``http://`` endpoints, so
+    forcing https would break legitimate non-TLS targets. Callers who need TLS
+    enforcement can check the scheme themselves.
+    """
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https"):
+        raise RuntimeError(
+            f"Parse base_url must be an http(s) URL; got scheme {parts.scheme!r} in {url!r}."
+        )
+    if not parts.hostname:
+        raise RuntimeError(f"Parse base_url has no host: {url!r}.")
+    if parts.username or parts.password:
+        raise RuntimeError(
+            "Parse base_url must not embed credentials (user:pass@host); "
+            "set the API key via PARSE_API_KEY or `parse login` instead."
+        )
+    return url
+
+
+@dataclass(frozen=True)
+class Config:
+    # repr=False: a Config travels through tracebacks / logged exception context,
+    # and the secrets must never ride along in its repr.
+    api_key: Optional[str] = field(repr=False)
+    base_url: str
+    # OAuth access token from `parse login --web` (host-gated exactly like
+    # api_key). Used as ``Authorization: Bearer`` when no api_key is present.
+    access_token: Optional[str] = field(default=None, repr=False)
+
+    def require_key(self) -> str:
+        # Type-invariant, not a runtime re-check: resolve() is the sole writer
+        # that gates the key, but a hand-built Config(api_key=k, base_url=evil)
+        # must withhold too — this is the gate for any Config not produced by
+        # resolve(). The predicate is self-contained (rejects non-http(s) and
+        # non-ASCII hosts), so this check is the full local invariant.
+        trusted = _host_is_trusted(self.base_url)
+        if self.api_key and trusted:
+            return self.api_key
+        if not trusted:
+            raise RuntimeError(
+                f"Parse API requests to {self.base_url!r} cannot carry an API key — "
+                f"it is not a trusted Parse API host. Point base_url at "
+                f"https://{CANONICAL_HOST} (the default) or a loopback URL for local dev."
+            )
+        raise RuntimeError(
+            "No Parse API key found. Set PARSE_API_KEY, run `parse login`, "
+            "or pass api_key= to the generated root client."
+        )
+
+    def auth_headers(self) -> dict:
+        """The auth header dict to attach to a Parse request: ``X-API-Key`` when
+        an api_key is set, else ``Authorization: Bearer`` from a web-login token.
+        Raises RuntimeError (untrusted host, or no credential) — the single
+        chokepoint both the CLI transport and the runtime sink use, so the
+        key↔host / token↔host binding holds everywhere.
+        """
+        trusted = _host_is_trusted(self.base_url)
+        if not trusted:
+            raise RuntimeError(
+                f"Parse API requests to {self.base_url!r} cannot carry credentials — "
+                f"it is not a trusted Parse API host. Point base_url at "
+                f"https://{CANONICAL_HOST} (the default) or a loopback URL for local dev."
+            )
+        if self.api_key:
+            return {"X-API-Key": self.api_key}
+        if self.access_token:
+            return {"Authorization": f"Bearer {self.access_token}"}
+        raise RuntimeError(
+            "No Parse credentials found. Run `parse login` (API key) or "
+            "`parse login --web` (browser), or set PARSE_API_KEY."
+        )
+
+
+def _read_credentials_file() -> dict:
+    # Single fd for stat + chmod + read: O_NOFOLLOW refuses a symlinked creds
+    # file outright (save_credentials never writes one) and fstat/fchmod
+    # operate on the OPEN fd — no path re-lookup, so the check-then-chmod
+    # window of the old is_symlink()/chmod() pair (TOCTOU) is unrepresentable.
+    try:
+        fd = os.open(CREDENTIALS_PATH, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    except OSError:  # missing, unreadable, or ELOOP (symlink under O_NOFOLLOW)
+        return {}
+    try:
+        with os.fdopen(fd, "r") as f:
+            # Re-tighten a pre-existing loose file at the single read
+            # chokepoint (save_credentials already writes 0600).
+            if os.fstat(f.fileno()).st_mode & 0o077:
+                try:
+                    os.fchmod(f.fileno(), 0o600)
+                except (OSError, AttributeError):
+                    pass
+            return json.loads(f.read())
+    except Exception:
+        return {}
+
+
+def resolve(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Config:
+    creds = _read_credentials_file()
+    key = api_key or os.environ.get("PARSE_API_KEY") or creds.get("api_key")
+    url = base_url or os.environ.get("PARSE_API_BASE_URL") or creds.get("base_url") or DEFAULT_BASE_URL
+    if not isinstance(url, str):
+        # A hand-edited credentials file can carry a non-string base_url
+        # (e.g. ``"base_url": 123``); surface a clear error instead of an opaque
+        # AttributeError from the rstrip/validate below.
+        raise RuntimeError(
+            f"Parse base_url must be a string; got {type(url).__name__} ({url!r}). "
+            "Check ~/.config/parse/credentials and the PARSE_API_BASE_URL env var."
+        )
+    url = _validate_base_url(url.rstrip("/"))   # runs FIRST: rejects userinfo / non-http(s) / hostless
+    # OAuth access token from `parse login --web` (env override first, then the
+    # creds file's `oauth` block). Gated by the SAME host predicate as the key.
+    _o = creds.get("oauth")
+    oauth = _o if isinstance(_o, dict) else {}
+    token = os.environ.get("PARSE_ACCESS_TOKEN") or oauth.get("access_token")
+    token = token if isinstance(token, str) and token else None
+    # Gate the SECRETS, not the URL: base_url is always preserved (raw HTTP against
+    # any structurally-valid host keeps working), but key/token only ride to the
+    # canonical prod host (https), loopback, or an opted-in extra host. This makes
+    # "a Config carrying a real credential for an untrusted host" unrepresentable.
+    trusted = _host_is_trusted(url)
+    return Config(
+        api_key=(key if trusted else None),
+        base_url=url,
+        access_token=(token if trusted else None),
+    )
+
+
+def read_oauth() -> dict:
+    """The stored ``oauth`` block ({access_token, refresh_token, expires_at,
+    client_id}) from the credentials file, or {} — used by the refresh path."""
+    creds = _read_credentials_file()
+    oauth = creds.get("oauth")
+    return oauth if isinstance(oauth, dict) else {}
+
+
+def save_oauth_credentials(
+    *, access_token: str, refresh_token: Optional[str], expires_at: Optional[int],
+    client_id: Optional[str], base_url: str,
+) -> str:
+    """Persist an `oauth` block to the credentials file (0600, atomic, no symlink
+    follow — same writer as save_credentials). Refuses an untrusted host, so a
+    web-login token is never stored against a host it would then leak to. Returns
+    the saved base_url."""
+    base_url = base_url.rstrip("/")
+    _validate_base_url(base_url)
+    if not _host_is_trusted(base_url):
+        raise RuntimeError(
+            f"Refusing to save web-login credentials for {base_url!r} — it is not a "
+            f"trusted Parse API host. Use https://{CANONICAL_HOST} (the default), a "
+            f"loopback URL, or an opted-in PARSE_EXTRA_TRUSTED_HOSTS host."
+        )
+    current = _read_credentials_file()
+    current["base_url"] = base_url
+    current["oauth"] = {
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "expires_at": expires_at,
+        "client_id": client_id,
+    }
+    _write_credentials_dict(current)
+    return base_url
+
+
+def save_credentials(api_key: Optional[str] = None, base_url: Optional[str] = None) -> str:
+    """Persist key/url to the credentials file with 0600 perms — atomically and
+    without ever writing through a symlink at the target path. Returns the
+    base_url now stored in the file (so callers can echo what was SAVED, not what
+    a later env-var override would resolve to).
+
+    The file holds a plaintext API key, so it must never be world-readable, even
+    momentarily. We write to a fresh 0600 temp file in the same directory
+    (``mkstemp`` uses ``O_CREAT|O_EXCL``, so there is no pre-existing inode to
+    follow) and then ``os.replace`` it over the target. ``os.replace`` swaps the
+    NAME: a symlink planted at ``CREDENTIALS_PATH`` is replaced, never written
+    through — closing both the world-readable write window and the symlink-follow
+    redirect.
+
+    Write-path host gate: the EFFECTIVE merged base_url (the file's, when the
+    caller passes none) must be a trusted host on EVERY write — raising before
+    anything is created or modified. A persisted key paired with an untrusted
+    host is unrepresentable; saving a key over a pre-existing poisoned file
+    refuses instead of arming it.
+    """
+    current = _read_credentials_file()
+    if api_key is not None:
+        current["api_key"] = api_key
+    if base_url is not None:
+        current["base_url"] = base_url.rstrip("/")
+    effective = current.get("base_url", DEFAULT_BASE_URL)
+    if not isinstance(effective, str):
+        raise RuntimeError(
+            f"Parse base_url must be a string; got {type(effective).__name__} "
+            f"({effective!r}). Check ~/.config/parse/credentials."
+        )
+    _validate_base_url(effective)
+    if not _host_is_trusted(effective):
+        raise RuntimeError(
+            f"Refusing to save credentials for {effective!r} — it is not a trusted "
+            f"Parse API host, so the saved key would leak there on every request. "
+            f"Use https://{CANONICAL_HOST} (the default) or a loopback URL for local dev."
+        )
+    _write_credentials_dict(current)
+    return current.get("base_url", DEFAULT_BASE_URL)
+
+
+def _write_credentials_dict(data: dict) -> None:
+    """Atomically write the credentials dict at 0600 without following a symlink
+    at the target (mkstemp uses O_CREAT|O_EXCL; os.replace swaps the NAME, so a
+    planted symlink is replaced, never written through). Shared by
+    save_credentials + save_oauth_credentials so the secret-handling is identical."""
+    parent = CREDENTIALS_PATH.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    try:
+        parent.chmod(0o700)
+    except OSError:
+        pass
+    payload = json.dumps(data, indent=2)
+    fd, tmp = tempfile.mkstemp(dir=parent, prefix=".credentials.", suffix=".tmp")
+    try:
+        os.write(fd, payload.encode("utf-8"))
+        os.close(fd)
+        os.replace(tmp, CREDENTIALS_PATH)
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise