convergent-cli 0.1.0__py3-none-any.whl

convergent_cli/__init__.py

@@ -0,0 +1 @@
+"""The Convergent command line tool (`cv`)."""

convergent_cli/auth.py

@@ -0,0 +1,227 @@
+"""High-level auth commands for the public CLI."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from shutil import rmtree
+
+from convergent_cli.control_client import get_control_json_at
+from convergent_cli.customer_client import forget_calibration_tokens
+from convergent_cli.errors import (
+    AuthError,
+    ControlRefusedError,
+    NetworkError,
+    SessionRejectedError,
+    UsageError,
+)
+from convergent_cli.oauth import browser_sign_in, headless_sign_in, resolve_client_id
+from convergent_cli.output import json_text
+from convergent_cli.sessions import (
+    StoredSession,
+    access_token_for_profile,
+    remove_session,
+    save_session,
+    session_path,
+)
+from convergent_cli.state import (
+    Config,
+    active_profile_name,
+    config_path,
+    load_config,
+    save_config,
+    validate_origin,
+    validate_profile_name,
+    write_private_file,
+)
+from convergent_cli.transport import Transport, UrllibTransport
+
+
+@dataclass(frozen=True, slots=True)
+class LoginResult:
+    profile_name: str
+    origin: str
+    session_file: Path
+    identity: Mapping[str, object]
+
+
+def login(
+    *,
+    profile_name: str | None,
+    control_api_url: str | None,
+    client_id: str | None,
+    headless: bool,
+    transport: Transport | None = None,
+    announce: Callable[[str], None] = print,
+    read_redirect: Callable[[], str] = input,
+) -> LoginResult:
+    config = load_config()
+    name, origin, updated = _login_target(config, profile_name, control_api_url)
+    oauth_client = resolve_client_id(client_id, origin)
+    http = transport or UrllibTransport()
+    if headless:
+        session = headless_sign_in(
+            origin=origin,
+            client_id=oauth_client,
+            transport=http,
+            announce=announce,
+            read_redirect=read_redirect,
+        )
+    else:
+        session = browser_sign_in(
+            origin=origin,
+            client_id=oauth_client,
+            transport=http,
+            announce=announce,
+        )
+    session_file = _save_login_state(name, updated, session)
+    identity = _verify_login(name, origin, session.access_token, http)
+    return LoginResult(
+        profile_name=name, origin=origin, session_file=session_file, identity=identity
+    )
+
+
+def logout(*, profile_name: str | None) -> tuple[str, bool]:
+    config = load_config()
+    name = validate_profile_name(profile_name) if profile_name else active_profile_name(config)
+    config.profile(name)
+    removed = remove_session(name)
+    cache = config_path().parent / "calibration-tokens"
+    if cache.exists():
+        rmtree(cache)
+    forget_calibration_tokens()
+    return name, removed
+
+
+def whoami(
+    *,
+    profile_name: str | None,
+    transport: Transport | None = None,
+    now: datetime | None = None,
+) -> Mapping[str, object]:
+    http = transport or UrllibTransport()
+    config = load_config()
+    name = validate_profile_name(profile_name) if profile_name else active_profile_name(config)
+    profile = config.profile(name)
+    token = access_token_for_profile(
+        name,
+        profile.origin,
+        transport=http,
+        now=now or datetime.now(UTC),
+    )
+    identity = get_control_json_at(
+        profile.origin, "/v1/auth/me", access_token=token, transport=http
+    )
+    return _identity_payload(name, profile.origin, identity)
+
+
+def whoami_json(payload: Mapping[str, object]) -> str:
+    return json_text(payload)
+
+
+def _login_target(
+    config: Config,
+    profile_name: str | None,
+    control_api_url: str | None,
+) -> tuple[str, str, Config]:
+    name = validate_profile_name(profile_name) if profile_name else active_profile_name(config)
+    existing = config.profiles.get(name)
+    if existing is None and control_api_url is None:
+        raise UsageError(
+            f"profile {name!r} does not exist yet, so cv has no origin for it "
+            "and will not guess one. Pass --control-api-url ORIGIN."
+        )
+    if control_api_url:
+        origin = validate_origin(control_api_url)
+    elif existing is not None:
+        origin = existing.origin
+    else:
+        raise AssertionError("unreachable login target state")
+    return name, origin, config.with_profile_origin(name, origin)
+
+
+def _verify_login(
+    profile_name: str, origin: str, access_token: str, http: Transport
+) -> Mapping[str, object]:
+    try:
+        identity = get_control_json_at(
+            origin, "/v1/auth/me", access_token=access_token, transport=http
+        )
+    except SessionRejectedError as error:
+        raise SessionRejectedError(
+            f"the new session was rejected by {origin}; retry `cv login --profile {profile_name}`"
+        ) from error
+    except ControlRefusedError as error:
+        raise ControlRefusedError(
+            f"signed in, but your account has no access to an organization at {origin}; "
+            "ask an administrator to add you"
+        ) from error
+    except NetworkError as error:
+        raise NetworkError(
+            f"stored the session for profile {profile_name!r} but could not verify it: {error}"
+        ) from error
+    return _identity_payload(profile_name, origin, identity)
+
+
+def _identity_payload(
+    profile_name: str,
+    origin: str,
+    identity: Mapping[str, object],
+) -> Mapping[str, object]:
+    user_id = _required_string(identity, "user_id")
+    email = _required_string(identity, "email")
+    organization_id = _required_string(identity, "organization_id")
+    is_staff = identity.get("is_staff")
+    if not isinstance(is_staff, bool):
+        raise AuthError("/v1/auth/me returned no usable is_staff value")
+    permissions = identity.get("permissions")
+    if not isinstance(permissions, list) or not all(
+        isinstance(permission, str) for permission in permissions
+    ):
+        raise AuthError("/v1/auth/me returned no usable permissions list")
+    return {
+        "profile": profile_name,
+        "origin": origin,
+        "user_id": user_id,
+        "email": email,
+        "organization_id": organization_id,
+        "is_staff": is_staff,
+        "permissions": permissions,
+    }
+
+
+def _save_login_state(profile_name: str, config: Config, session: StoredSession) -> Path:
+    config_file = config_path()
+    session_file = session_path(profile_name)
+    previous_config = _file_snapshot(config_file)
+    previous_session = _file_snapshot(session_file)
+    try:
+        saved_session = save_session(profile_name, session)
+        save_config(config)
+        return saved_session
+    except BaseException:
+        _restore_file(config_file, previous_config)
+        _restore_file(session_file, previous_session)
+        raise
+
+
+def _file_snapshot(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    return path.read_text(encoding="utf-8")
+
+
+def _restore_file(path: Path, contents: str | None) -> None:
+    if contents is None:
+        path.unlink(missing_ok=True)
+        return
+    write_private_file(path, contents)
+
+
+def _required_string(identity: Mapping[str, object], key: str) -> str:
+    value = identity.get(key)
+    if not isinstance(value, str) or not value:
+        raise AuthError(f"/v1/auth/me returned no usable {key}")
+    return value

convergent_cli/build_context.py

@@ -0,0 +1,225 @@
+"""Reproducible build-context archives for hosted builds, and their safe extraction.
+
+``pack_build_context`` packs one project directory with a root ``Dockerfile``.
+It leaves out, at any depth, version-control and cache directories, local
+credential directories and files, and ``.env`` files (``SKIPPED_DIRECTORIES``
+and ``SKIPPED_FILES``). With ``dockerignore`` it also leaves out what the root
+``.dockerignore`` excludes, by Docker's rules: ``*``, ``?``, ``[...]``, and
+``**`` patterns relative to the root, a pattern that matches a directory
+excludes everything under it, ``!`` includes a path again, and the last
+matching line wins. The root ``Dockerfile`` is always kept. The archive is
+reproducible: entries in path order, no owner or time, modes of 0755 or 0644 by
+the owner's execute bit, and a gzip header with no name or time.
+
+``extract_build_context`` unpacks an archive into a new directory, refusing
+anything but files and directories, paths outside it, duplicate entries, and
+archives over the build service's limits, which this package repeats because it
+cannot import the server. Nothing reaches the target unless every entry is
+written.
+"""
+
+from __future__ import annotations
+
+import gzip
+import io
+import os
+import posixpath
+import re
+import stat
+import tarfile
+import tempfile
+from pathlib import Path, PurePosixPath
+
+from convergent_cli.errors import UsageError
+
+MAX_UPLOAD_BYTES = 6 * 1024 * 1024
+"""The largest archive the server takes in one request; a larger one needs chunked upload."""
+MAX_ARCHIVE_BYTES = 25 * 1024 * 1024
+MAX_EXPANDED_BYTES = 100 * 1024 * 1024
+MAX_ENTRIES = 10_000
+SKIPPED_DIRECTORIES = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "node_modules",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".aws",
+        ".docker",
+        ".gnupg",
+        ".kube",
+        ".ssh",
+    }
+)
+SKIPPED_FILES = frozenset(
+    {
+        ".DS_Store",
+        ".env",
+        ".envrc",
+        ".git-credentials",
+        ".netrc",
+        ".npmrc",
+        ".pgpass",
+        ".pypirc",
+    }
+)
+
+
+def pack_build_context(root: Path, *, dockerignore: bool = False) -> tuple[bytes, list[str]]:
+    """``root`` as a reproducible tar.gz, and the paths it holds."""
+    if not (root / "Dockerfile").is_file():
+        raise UsageError(f"{root} has no Dockerfile at its root")
+    rules = _dockerignore_rules(root) if dockerignore else []
+    # Without a ``!`` line nothing under an excluded directory comes back, so skip walking it.
+    prune = bool(rules) and not any(keep for keep, _ in rules)
+    entries: list[Path] = []
+    for parent, dirs, names in os.walk(root):
+        relative_parent = Path(parent).relative_to(root).as_posix()
+        dirs[:] = [
+            name
+            for name in dirs
+            if name not in SKIPPED_DIRECTORIES
+            and not (prune and _ignored(rules, posixpath.normpath(f"{relative_parent}/{name}")))
+        ]
+        entries += [
+            Path(parent, name)
+            for name in (*dirs, *names)
+            if name not in SKIPPED_FILES and not name.startswith(".env.")
+        ]
+    paths = sorted(path.relative_to(root).as_posix() for path in entries)
+    if rules:
+        paths = dockerignore_kept(root, paths)
+    buffer = io.BytesIO()
+    with (
+        gzip.GzipFile(fileobj=buffer, mode="wb", mtime=0) as zipped,
+        tarfile.open(fileobj=zipped, mode="w", format=tarfile.PAX_FORMAT) as archive,
+    ):
+        for relative in paths:
+            path = root / relative
+            info = tarfile.TarInfo(relative)
+            mode = path.lstat().st_mode
+            if stat.S_ISDIR(mode):
+                info.type, info.mode = tarfile.DIRTYPE, 0o755
+                archive.addfile(info)
+            elif stat.S_ISREG(mode):
+                info.size, info.mode = path.stat().st_size, 0o755 if mode & 0o100 else 0o644
+                with path.open("rb") as content:
+                    archive.addfile(info, content)
+            else:
+                raise UsageError(f"{relative} is a symlink or special file; copy its target")
+    data = buffer.getvalue()
+    if len(data) > MAX_UPLOAD_BYTES:
+        hint = "; leave out what the image does not need with .dockerignore" if dockerignore else ""
+        raise UsageError(f"the build context is over 6 MiB compressed ({len(data)} bytes){hint}")
+    return data, paths
+
+
+def dockerignore_kept(root: Path, paths: list[str]) -> list[str]:
+    """``paths``, relative ``/`` paths under ``root``, less what its ``.dockerignore`` leaves out,
+    as ``docker build`` does: the root ``Dockerfile`` stays, and a kept path keeps the directories
+    above it."""
+    rules = _dockerignore_rules(root)
+    if not rules:
+        return paths
+    kept = {path for path in paths if path == "Dockerfile" or not _ignored(rules, path)}
+    kept |= {str(up) for path in kept for up in PurePosixPath(path).parents if str(up) != "."}
+    return [path for path in paths if path in kept]
+
+
+def _dockerignore_rules(root: Path) -> list[tuple[bool, re.Pattern[str]]]:
+    """The root ``.dockerignore`` as ``(keep, pattern)`` rules, in file order."""
+    path = root / ".dockerignore"
+    if not path.is_file():
+        return []
+    rules = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        keep = line.startswith("!")
+        pattern = posixpath.normpath(line[1:].strip() if keep else line).lstrip("/")
+        if pattern and pattern != ".":
+            rules.append((keep, re.compile(_pattern_regex(pattern))))
+    return rules
+
+
+def _pattern_regex(pattern: str) -> str:
+    """A Docker ignore pattern as an anchored regular expression over ``/`` paths."""
+    out, i = ["^"], 0
+    while i < len(pattern):
+        char = pattern[i]
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+            continue
+        if pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+            continue
+        if char == "*":
+            out.append("[^/]*")
+        elif char == "?":
+            out.append("[^/]")
+        elif char == "\\" and i + 1 < len(pattern):
+            i += 1
+            out.append(re.escape(pattern[i]))
+        elif char == "[" and (end := pattern.find("]", i + 2)) != -1:
+            body = pattern[i + 1 : end]
+            out.append("[" + ("^" + body[1:] if body[0] in "!^" else body) + "]")
+            i = end
+        else:
+            out.append(re.escape(char))
+        i += 1
+    out.append("$")
+    return "".join(out)
+
+
+def _ignored(rules: list[tuple[bool, re.Pattern[str]]], path: str) -> bool:
+    """Whether the last rule matching ``path`` or a directory above it excludes it."""
+    candidates = [path, *(str(up) for up in PurePosixPath(path).parents if str(up) != ".")]
+    ignored = False
+    for keep, pattern in rules:
+        if any(pattern.match(candidate) for candidate in candidates):
+            ignored = not keep
+    return ignored
+
+
+def extract_build_context(data: bytes, target: Path) -> int:
+    """Unpack ``data`` into ``target``, an absent or empty directory; return the file count."""
+    if len(data) > MAX_ARCHIVE_BYTES:
+        raise UsageError("the archive is over 25 MiB")
+    try:
+        with gzip.GzipFile(fileobj=io.BytesIO(data)) as source:
+            raw = source.read(MAX_EXPANDED_BYTES + 1)
+        if len(raw) > MAX_EXPANDED_BYTES:
+            raise UsageError("the archive expands to over 100 MiB")
+        with (
+            tarfile.open(fileobj=io.BytesIO(raw), mode="r:") as archive,
+            tempfile.TemporaryDirectory(prefix=".cv-pull-", dir=target.parent) as temporary,
+        ):
+            members = archive.getmembers()
+            names = [posixpath.normpath(member.name) for member in members]
+            if len(members) > MAX_ENTRIES or len(set(names)) != len(names):
+                raise UsageError("the archive has too many or duplicate entries")
+            if not all(
+                (member.isfile() and not member.issparse()) or member.isdir() for member in members
+            ):
+                raise UsageError("the archive holds a link or special file")
+            if any(name.startswith(("/", "../")) or name == ".." for name in names):
+                raise UsageError("the archive holds a path outside its directory")
+            staging = Path(temporary) / "out"
+            staging.mkdir()
+            archive.extractall(staging, filter="data")
+            staging.rename(target)
+    except (OSError, EOFError, tarfile.TarError) as exc:
+        raise UsageError(f"the archive could not be extracted: {exc}") from None
+    return sum(member.isfile() for member in members)
+
+
+__all__ = ["extract_build_context", "pack_build_context"]