rengo-cli 0.1.0__tar.gz

rengo_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/

rengo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: rengo-cli
+Version: 0.1.0
+Summary: Public Rengo developer authentication and package credential helper
+Requires-Python: >=3.11
+Requires-Dist: cryptography<51,>=44
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: keyring==25.7.0
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: portalocker<4,>=3

rengo_cli-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rengo-cli"
+version = "0.1.0"
+description = "Public Rengo developer authentication and package credential helper"
+requires-python = ">=3.11"
+dependencies = [
+  "cryptography>=44,<51",
+  "httpx>=0.28,<0.29",
+  "keyring==25.7.0",
+  "platformdirs>=4,<5",
+  "portalocker>=3,<4",
+]
+
+[project.scripts]
+rengo-auth = "rengo_cli.main:main"
+# pnpm tokenHelper launcher; other gateways reach it through per-origin links
+# (rengo_cli.npm).
+rengo-pnpm-token = "rengo_cli.npm:main"
+# uv's subprocess keyring provider runs whatever `keyring` is on PATH, and a
+# dependency's executables are not linked by `uv tool install`, so the CLI
+# ships the one whose environment carries the Rengo backend. Other services
+# still reach the OS store through keyring's chainer.
+keyring = "keyring.cli:main"
+
+[project.entry-points."keyring.backends"]
+rengo = "rengo_cli.keyring_backend"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.12", "mypy>=1.15"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rengo_cli"]
+
+# The public sdist carries the code and what builds it, not the test suite.
+[tool.hatch.build.targets.sdist]
+exclude = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+files = ["src/rengo_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rengo_cli-0.1.0/src/rengo_cli/__init__.py

@@ -0,0 +1 @@
+"""Rengo package credentials for uv and pnpm."""

rengo_cli-0.1.0/src/rengo_cli/auth.py

@@ -0,0 +1,133 @@
+import math
+import time
+from collections.abc import Callable
+from typing import Any
+
+from .config import OAuthConfig, login_hint
+from .errors import AuthError, ConnectionUnavailable, LoginRequired, OAuthRejected
+from .oauth import Provider, authorize, token_bundle
+from .storage import Store
+
+
+class Auth:
+    def __init__(self, store: Store, provider: Provider | None = None):
+        self.store = store
+        self.provider = provider or Provider()
+
+    def _session(self) -> dict[str, Any]:
+        value = self.store.read()
+        if not value or value.get("logged_out"):
+            raise LoginRequired(f"No Rengo login. Run {login_hint(self.store.origin)}.")
+        if value.get("pending"):
+            raise LoginRequired(
+                f"Previous token exchange is uncertain; run {login_hint(self.store.origin)} again."
+            )
+        try:
+            for field in ("issued_at", "expires_at"):
+                if not isinstance(value[field], (int, float)) or not math.isfinite(value[field]):
+                    raise ValueError
+            if not 120 < value["expires_at"] - value["issued_at"] <= 86400:
+                raise ValueError
+            for field in ("access_token", "refresh_token"):
+                if not isinstance(value[field], str) or not value[field]:
+                    raise ValueError
+            OAuthConfig.parse(value["oauth"], self.store.origin)
+        except (KeyError, TypeError, ValueError):
+            raise LoginRequired(
+                f"Invalid credential state; run {login_hint(self.store.origin)} again."
+            ) from None
+        return value
+
+    def access_token(self) -> str:
+        with self.store.lock():
+            value = self._session()
+            now = time.time()
+            if value["expires_at"] > now + 120:
+                return str(value["access_token"])
+            config = OAuthConfig.parse(value["oauth"], self.store.origin)
+            # Commit before sending: process death and uncertain network responses must
+            # never cause a successor process to replay a possibly consumed refresh token.
+            # The provider rotates refresh tokens and detects reuse: replaying a consumed one
+            # revokes the whole grant, live successor included, forcing a browser login.
+            value["pending"] = True
+            self.store.write(value, value["storage"])
+            try:
+                raw = self.provider.exchange(
+                    config, {"grant_type": "refresh_token", "refresh_token": value["refresh_token"]}
+                )
+            except ConnectionUnavailable:
+                value["pending"] = False
+                self.store.write(value, value["storage"])
+                raise
+            except OAuthRejected as error:
+                # The service answered definitively, so no unknown outcome can have
+                # consumed this refresh token. A definitive 4xx on a refresh_token grant
+                # means the stored grant cannot be used again, whatever the provider
+                # names the error: some answer invalid_request, not invalid_grant.
+                self.store.clear()
+                detail = f" ({error.code})" if error.code else ""
+                raise LoginRequired(
+                    f"Rengo login is no longer valid{detail}; "
+                    f"run {login_hint(self.store.origin)} again."
+                ) from None
+            successor = token_bundle(raw, config, now)
+            self.store.write(successor, value["storage"])
+            return str(successor["access_token"])
+
+    def login(
+        self,
+        present: Callable[[str], None],
+        *,
+        storage: str = "native",
+        timeout: float = 180,
+        port: int = 0,
+    ) -> None:
+        # Prove storage is available before the browser creates a new grant.
+        with self.store.lock():
+            self.store.prepare(storage)
+        config = self.provider.discover(self.store.origin)
+        code, verifier, redirect = authorize(config, present, timeout=timeout, port=port)
+        # Holding the same lock through exchange and commit makes final mutations linearizable.
+        with self.store.lock():
+            issued_at = time.time()
+            raw = self.provider.exchange(
+                config,
+                {
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "code_verifier": verifier,
+                    "redirect_uri": redirect,
+                },
+            )
+            bundle = token_bundle(raw, config, issued_at)
+            self.store.write(bundle, storage)
+
+    def logout(self) -> bool:
+        with self.store.lock():
+            revoked = True
+            try:
+                value = self.store.read()
+                if value and not value.get("logged_out"):
+                    config = OAuthConfig.parse(value["oauth"], self.store.origin)
+                    self.provider.revoke(config, value["refresh_token"])
+                    revoked = not value.get("pending", False)
+            except ConnectionUnavailable:
+                # Clearing here would destroy the only copy of an unrevoked refresh token.
+                raise AuthError(
+                    "Cannot reach the OAuth service to revoke this login; retry when online."
+                ) from None
+            except (AuthError, KeyError):
+                revoked = False
+            self.store.clear()
+            return revoked
+
+    def status(self) -> dict[str, Any]:
+        with self.store.lock():
+            value = self._session()
+            return {
+                "origin": self.store.origin,
+                "environment": value["oauth"]["environment"],
+                "storage": value["storage"],
+                "access_expires_at": value["expires_at"],
+                "refresh_needed": value["expires_at"] <= time.time() + 120,
+            }

rengo_cli-0.1.0/src/rengo_cli/autologin.py

@@ -0,0 +1,105 @@
+"""The browser login a credential lookup starts itself when no usable grant is stored.
+
+uv (through the keyring backend) and pnpm (through the token helper) ask for a
+credential as subprocesses whose stdout they capture, so everything said to the
+person goes to the controlling terminal instead. With no terminal, in CI, or
+with RENGO_AUTH_NO_AUTO_LOGIN set, the lookup fails exactly as it would without
+this module, and the error names the login command.
+
+Only `LoginRequired` starts a login: an offline refresh, a busy lock or a locked
+OS store is not fixed by a new grant, and a login would throw away a refresh
+token that still works.
+"""
+
+import contextlib
+import os
+import sys
+import webbrowser
+from collections.abc import Iterator
+from typing import TextIO
+
+from .auth import Auth
+from .errors import AuthError, LoginRequired
+from .storage import Store
+
+OPT_OUT_ENV = "RENGO_AUTH_NO_AUTO_LOGIN"
+LOGIN_TIMEOUT = 180.0
+
+
+def terminal() -> TextIO | None:
+    """The person's terminal, or None when nobody is there to finish a login."""
+    if os.name == "nt" or os.environ.get("CI") or os.environ.get(OPT_OUT_ENV):
+        return None
+    try:
+        return open("/dev/tty", "w")
+    except OSError:
+        return None
+
+
+@contextlib.contextmanager
+def stdout_to_stderr() -> Iterator[None]:
+    """Keep a browser launcher's output off stdout, which pnpm takes as the header."""
+    sys.stdout.flush()
+    saved = os.dup(1)
+    try:
+        os.dup2(2, 1)
+        yield
+    finally:
+        sys.stdout.flush()
+        os.dup2(saved, 1)
+        os.close(saved)
+
+
+def access_token(store: Store, *, configure_pnpm: bool) -> str:
+    """The stored access token, logging in through the browser first if none is usable."""
+    try:
+        return Auth(store).access_token()
+    except LoginRequired:
+        tty = terminal()
+        if tty is None:
+            raise
+    with tty:
+        try:
+            return _login(store, tty, configure_pnpm=configure_pnpm)
+        except KeyboardInterrupt:
+            raise LoginRequired("Rengo login cancelled.") from None
+
+
+def _login(store: Store, tty: TextIO, *, configure_pnpm: bool) -> str:
+    # uv and pnpm may look up several URLs at once; the first lookup logs in and
+    # the rest find its grant once the lock is theirs.
+    with store.login_lock(LOGIN_TIMEOUT + 30):
+        try:
+            return Auth(store).access_token()
+        except LoginRequired:
+            pass
+        print(
+            f"No usable Rengo login for {store.origin}; opening your browser to log in "
+            "(Ctrl-C cancels).",
+            file=tty,
+            flush=True,
+        )
+
+        def present(url: str) -> None:
+            # URL has PKCE challenge/state, never a token or authorization code.
+            with stdout_to_stderr():
+                opened = webbrowser.open(url)
+            if not opened:
+                print("Open this authorization URL in your browser:\n" + url, file=tty, flush=True)
+
+        auth = Auth(store)
+        auth.login(present, timeout=LOGIN_TIMEOUT)
+        print(f"Logged in to Rengo ({store.origin}).", file=tty, flush=True)
+        if configure_pnpm:
+            from . import npm
+
+            try:
+                path = npm.configure(store.origin)
+                print(
+                    f"pnpm: {path} routes {npm.registry_url(store.origin)} through the CLI.",
+                    file=tty,
+                    flush=True,
+                )
+            except AuthError as error:
+                print(f"pnpm: not configured. {error}", file=tty, flush=True)
+        return auth.access_token()

rengo_cli-0.1.0/src/rengo_cli/config.py

@@ -0,0 +1,208 @@
+import tomllib
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from .errors import AuthError
+
+# The gateway used outside an estate checkout. Inside one, the checkout's own
+# package files name the gateway, and everything else about it is learned from
+# that gateway's discovery document.
+DEFAULT_GATEWAY = "https://packages.rengoai.com"
+DEFAULT_AUTHORIZATION_ENDPOINT = "https://app.rengoai.com/oauth/authorize"
+
+
+def canonical_origin(value: Any) -> str:
+    """`https://host`, lower-cased: no userinfo, path, query, fragment or port but 443."""
+    if not isinstance(value, str) or any(c.isspace() for c in value) or "\\" in value:
+        raise AuthError("Expected a bare HTTPS origin such as https://host.")
+    parsed = urlsplit(value)
+    try:
+        port = parsed.port
+    except ValueError:
+        raise AuthError("Expected a bare HTTPS origin such as https://host.") from None
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in ("", "/")
+        or parsed.query
+        or parsed.fragment
+        or port not in (None, 443)
+    ):
+        raise AuthError("Expected a bare HTTPS origin such as https://host.")
+    return "https://" + parsed.hostname.lower()
+
+
+def origin_host(origin: str) -> str:
+    return canonical_origin(origin).removeprefix("https://")
+
+
+def _declared_gateway(url: object, suffix: str) -> str | None:
+    """The gateway origin a committed index or registry URL points at, or None."""
+    if not isinstance(url, str) or not url.endswith(suffix):
+        return None
+    parsed = urlsplit(url)
+    # uv index URLs carry the `__token__@` username the keyring answers for.
+    return "https://" + (parsed.hostname or "") + (f":{parsed.port}" if parsed.port else "")
+
+
+def project_gateway(start: Path | None = None) -> tuple[str, Path] | None:
+    """The gateway the estate checkout around `start` declares, or None outside one.
+
+    An estate commits its gateway twice: the `[[tool.uv.index]]` URL in
+    pyproject.toml and the `@rengoai:registry=` line in .npmrc. Whichever
+    directory up from `start` first holds either file decides, so a command
+    run anywhere inside a checkout acts on that estate's gateway.
+    """
+    for directory in [start or Path.cwd(), *(start or Path.cwd()).parents]:
+        pyproject, npmrc = directory / "pyproject.toml", directory / ".npmrc"
+        if not pyproject.is_file() and not npmrc.is_file():
+            continue
+        declared: set[str | None] = set()
+        if pyproject.is_file():
+            try:
+                indexes = tomllib.loads(pyproject.read_text())["tool"]["uv"]["index"]
+            except (OSError, tomllib.TOMLDecodeError, KeyError, TypeError):
+                indexes = []
+            for index in indexes if isinstance(indexes, list) else []:
+                if isinstance(index, dict):
+                    declared.add(_declared_gateway(index.get("url"), "/pypi/simple/"))
+        if npmrc.is_file():
+            for line in npmrc.read_text(errors="replace").splitlines():
+                if line.strip().startswith("@rengoai:registry="):
+                    declared.add(_declared_gateway(line.split("=", 1)[1].strip(), "/npm/"))
+        declared.discard(None)
+        if not declared:
+            return None
+        if len(declared) > 1:
+            raise AuthError(f"{directory} declares more than one package gateway.")
+        return canonical_origin(declared.pop()), directory
+    return None
+
+
+def resolve_gateway() -> tuple[str, str]:
+    """The gateway a command acts on and where the choice came from.
+
+    Inside an estate checkout, the gateway that checkout declares, taken as
+    written; anywhere else, the default.
+    """
+    declared = project_gateway()
+    if declared is None:
+        return DEFAULT_GATEWAY, "default"
+    return declared[0], f"project {declared[1]}"
+
+
+def login_hint(origin: str) -> str:
+    if origin == DEFAULT_GATEWAY:
+        return "rengo-auth login"
+    return f"rengo-auth login inside an estate checkout for {origin}"
+
+
+def service_origin(service: str) -> str | None:
+    """The origin uv or keyring is asking about, or None if it is not an https origin.
+
+    uv passes either the bare hostname or the full index URL. Only the https
+    authority on port 443 with no userinfo counts; `https://host:8443/` must
+    not inherit the credentials of `https://host/`.
+    """
+    candidate = service if "://" in service else "https://" + service
+    parsed = urlsplit(candidate)
+    if parsed.scheme != "https" or not parsed.hostname or parsed.query or parsed.fragment:
+        return None
+    try:
+        return canonical_origin("https://" + parsed.netloc)
+    except AuthError:
+        return None
+
+
+def https_url(value: Any) -> str:
+    if not isinstance(value, str) or any(c.isspace() for c in value):
+        raise AuthError("Invalid public OAuth configuration.")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.port not in (None, 443)
+        or parsed.query
+        or parsed.fragment
+        or "\\" in value
+    ):
+        raise AuthError("Invalid public OAuth configuration.")
+    return value
+
+
+@dataclass(frozen=True)
+class OAuthConfig:
+    version: int
+    environment: str
+    registry_url: str
+    client_id: str
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    revocation_endpoint: str
+    scopes: list[str]
+
+    @classmethod
+    def parse(cls, raw: Any, origin: str) -> "OAuthConfig":
+        """Validate a discovery document for the gateway it describes.
+
+        `origin` is the gateway the document was fetched from, or the origin a
+        stored bundle was bound to at login: a refresh is never routed by
+        rediscovery.
+        """
+        try:
+            origin = canonical_origin(origin)
+            config = cls(**{name: raw[name] for name in cls.__dataclass_fields__})
+            if config.version != 1 or type(config.version) is not int:
+                raise ValueError
+            # A label for `status`; it decides nothing.
+            if not isinstance(config.environment, str) or not config.environment:
+                raise ValueError
+            # Both registries have one fixed shape under the origin; a gateway
+            # that advertises the npm one must agree.
+            if config.registry_url != origin + "/pypi/simple/":
+                raise ValueError
+            npm_registry = raw.get("npm_registry_url") if isinstance(raw, dict) else None
+            if npm_registry is not None and npm_registry != origin + "/npm/":
+                raise ValueError
+            # Where the browser is sent. The default gateway pins it; another
+            # gateway's document is trusted for the page it names.
+            authorization = https_url(config.authorization_endpoint)
+            if origin == DEFAULT_GATEWAY and authorization != DEFAULT_AUTHORIZATION_ENDPOINT:
+                raise ValueError
+            if urlsplit(authorization).path != "/oauth/authorize":
+                raise ValueError
+            if not isinstance(config.client_id, str) or not 1 <= len(config.client_id) <= 256:
+                raise ValueError
+            issuer = https_url(config.issuer)
+            if urlsplit(issuer).path not in ("", "/"):
+                raise ValueError
+            # The trusted gateway delegates its OAuth authority to this issuer.
+            # Persist this binding with the grant; never rediscover to route a refresh.
+            for endpoint, path in (
+                (config.token_endpoint, "/v1/oauth2/token"),
+                (config.revocation_endpoint, "/v1/oauth2/revoke"),
+            ):
+                if https_url(endpoint) != issuer.rstrip("/") + path:
+                    raise ValueError
+            if (
+                not isinstance(config.scopes, list)
+                or not all(
+                    isinstance(s, str) and s and not any(c.isspace() for c in s)
+                    for s in config.scopes
+                )
+                or not {"packages:read", "offline_access"}.issubset(config.scopes)
+            ):
+                raise ValueError
+            return config
+        except (TypeError, KeyError, ValueError, AttributeError, AuthError):
+            raise AuthError("Invalid public OAuth configuration; contact Rengo support.") from None
+
+    def public_dict(self) -> dict[str, Any]:
+        return asdict(self)