apizit-cli 0.2.0b1__py3-none-any.whl

apizit_cli/context.py

@@ -0,0 +1,155 @@
+"""Non-secret machine and project preferences; credentials live in the OS vault."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from apizit_cli.errors import CliError, EXIT_USAGE
+
+DEFAULT_API_ORIGIN = "https://jxo6vbfwy0.execute-api.eu-central-1.amazonaws.com/v1"
+
+
+def normalize_origin(value: str) -> str:
+    parsed = urlsplit(value)
+    if (
+        not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+        or "\\" in value
+        or any(ord(char) < 33 for char in value)
+        or (
+            parsed.scheme != "https"
+            and not (
+                parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+            )
+        )
+    ):
+        raise CliError(
+            "APIZIT endpoint must be HTTPS (HTTP is allowed only on loopback).",
+            exit_code=EXIT_USAGE,
+        )
+    try:
+        parsed.port
+    except ValueError:
+        raise CliError("Invalid APIZIT endpoint port.", exit_code=EXIT_USAGE) from None
+    return value.rstrip("/")
+
+
+def home_directory() -> Path:
+    override = os.environ.get("APIZIT_CONFIG_HOME")
+    return Path(override).expanduser().resolve() if override else Path.home() / ".apizit"
+
+
+def read_json(path: Path) -> dict:
+    assert_safe_path(path)
+    if not path.exists():
+        return {}
+    try:
+        if path.is_symlink() or path.stat().st_size > 64 * 1024:
+            raise ValueError()
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise ValueError()
+        return value
+    except (OSError, ValueError):
+        raise CliError(
+            f"Cannot read APIZIT context at {path}.", code="CONTEXT_INVALID", exit_code=EXIT_USAGE
+        ) from None
+
+
+def write_json(path: Path, value: dict) -> None:
+    assert_safe_path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink():
+        raise CliError("Refusing to replace a symbolic context file.", exit_code=EXIT_USAGE)
+    descriptor, temporary = tempfile.mkstemp(prefix=".apizit-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as stream:
+            json.dump(value, stream, indent=2)
+            stream.write("\n")
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def assert_safe_path(path: Path) -> None:
+    for part in (path, *path.parents):
+        if part.is_symlink() or part.is_junction():
+            raise CliError(
+                "APIZIT context paths must not contain symbolic links or junctions.",
+                code="CONTEXT_INVALID",
+                exit_code=EXIT_USAGE,
+            )
+
+
+class ClientContext:
+    def __init__(self, *, workspace_id=None, root=None, endpoint=None):
+        self.root = Path(root or Path.cwd()).resolve()
+        self.path = home_directory() / "context.json"
+        self.project_path = self.root / ".apizit" / "project.json"
+        self.preferences = read_json(self.path)
+        self.project = read_json(self.project_path)
+        self.origin = normalize_origin(
+            endpoint or os.getenv("APIZIT_API_URL") or DEFAULT_API_ORIGIN
+        )
+        saved = self.preferences.get(self.origin, {})
+        if not isinstance(saved, dict):
+            raise CliError("Invalid saved endpoint context.", exit_code=EXIT_USAGE)
+        self.workspace_id = (
+            workspace_id
+            or os.getenv("APIZIT_WORKSPACE_ID")
+            or self.project.get("workspace_id")
+            or saved.get("workspace_id")
+        )
+        if self.project and self.project.get("origin") != self.origin:
+            raise CliError(
+                "This project is linked to another APIZIT endpoint.",
+                code="PROJECT_ENDPOINT_MISMATCH",
+                exit_code=EXIT_USAGE,
+            )
+        if self.project.get("api_id") and self.project.get("workspace_id") != self.workspace_id:
+            raise CliError(
+                "The linked API belongs to another workspace. Use an unlinked project context.",
+                code="PROJECT_WORKSPACE_MISMATCH",
+                exit_code=EXIT_USAGE,
+            )
+
+    def require_workspace(self):
+        import re
+
+        if not isinstance(self.workspace_id, str) or not re.fullmatch(
+            r"ws_[A-Za-z0-9_-]{1,128}", self.workspace_id
+        ):
+            raise CliError(
+                "Choose a workspace with apizit workspace use <id> or --workspace.",
+                code="WORKSPACE_REQUIRED",
+                exit_code=EXIT_USAGE,
+            )
+        return self.workspace_id
+
+    def select_workspace(self, workspace_id):
+        self.preferences[self.origin] = {"workspace_id": workspace_id}
+        write_json(self.path, self.preferences)
+        self.workspace_id = workspace_id
+
+    def bind_api(self, api_id):
+        ignore = self.root / ".gitignore"
+        assert_safe_path(ignore)
+        assert_safe_path(self.project_path)
+        previous = ignore.read_text(encoding="utf-8") if ignore.exists() else ""
+        write_json(
+            self.project_path,
+            {"origin": self.origin, "workspace_id": self.require_workspace(), "api_id": api_id},
+        )
+        if "/.apizit/" not in previous.splitlines():
+            with ignore.open("a", encoding="utf-8") as stream:
+                stream.write(
+                    ("\n" if previous and not previous.endswith("\n") else "") + "/.apizit/\n"
+                )

apizit_cli/credential_store.py

@@ -0,0 +1,170 @@
+"""Bounded OS-vault entries for providers with long renewal credentials."""
+
+import hashlib
+import hmac
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import time
+from contextlib import contextmanager
+
+from apizit_cli.context import assert_safe_path
+from apizit_cli.errors import CliError, EXIT_AUTH
+
+PART_SIZE = 1000  # Windows generic credentials allow 2560 bytes, stored as UTF-16 by keyring.
+MAX_PARTS = 32
+
+
+@contextmanager
+def session_lock(service, *, directory=None, timeout=30):
+    """Serialize renewal/revocation across processes; the lock contains no credentials."""
+    directory = directory or Path.home() / ".apizit" / "session-locks"
+    assert_safe_path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / (hashlib.sha256(service.encode()).hexdigest() + ".lock")
+    assert_safe_path(path)
+    with path.open("a+b") as stream:
+        if stream.tell() == 0:
+            stream.write(b"0")
+            stream.flush()
+        deadline = time.monotonic() + timeout
+        while True:
+            stream.seek(0)
+            try:
+                if os.name == "nt":
+                    import msvcrt
+
+                    msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK, 1)
+                else:
+                    import fcntl
+
+                    fcntl.flock(stream.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise CliError(
+                        "Another APIZIT process is renewing or clearing the session. Retry shortly.",
+                        code="SESSION_BUSY",
+                        exit_code=EXIT_AUTH,
+                    ) from None
+                time.sleep(0.05)
+        try:
+            yield
+        finally:
+            stream.seek(0)
+            if os.name == "nt":
+                msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(stream.fileno(), fcntl.LOCK_UN)
+
+
+class CredentialStore:
+    def __init__(self, vault, service):
+        self.vault = vault
+        self.service = service
+
+    def _parts(self, value):
+        if not value:
+            return []
+        record = json.loads(value)
+        if "vault_format" not in record:
+            return []
+        if (
+            record.get("vault_format") != 1
+            or not re.fullmatch(r"[0-9a-f]{32}", record.get("generation", ""))
+            or type(record.get("parts")) is not int
+            or not 1 <= record["parts"] <= MAX_PARTS
+            or not re.fullmatch(r"[0-9a-f]{64}", record.get("sha256", ""))
+        ):
+            raise ValueError("Invalid secure session manifest")
+        return [f"{self.service}:part:{record['generation']}:{i}" for i in range(record["parts"])]
+
+    def read(self):
+        self._recover()
+        for _ in range(3):
+            value = self.vault.get_password(self.service, "session")
+            parts = self._parts(value)
+            if not parts:
+                return value
+            fragments = [self.vault.get_password(part, "session") for part in parts]
+            if any(not isinstance(part, str) or len(part) > PART_SIZE for part in fragments):
+                if self.vault.get_password(self.service, "session") != value:
+                    continue  # A concurrent renewal replaced and cleaned the old generation.
+                raise ValueError("Incomplete secure session")
+            result = "".join(fragments)
+            if not hmac.compare_digest(
+                hashlib.sha256(result.encode()).hexdigest(), json.loads(value)["sha256"]
+            ):
+                raise ValueError("Invalid secure session integrity")
+            return result
+        raise ValueError("Secure session changed while reading")
+
+    def _clear_parts(self, parts):
+        for part in parts:
+            if self.vault.get_password(part, "session") is not None:
+                self.vault.delete_password(part, "session")
+
+    def _recover(self):
+        pending = self.vault.get_password(self.service + ":pending", "session")
+        if pending is None:
+            return
+        journal = json.loads(pending)
+        if not re.fullmatch(r"[0-9a-f]{64}", journal.get("target_sha256", "")):
+            raise ValueError("Invalid secure session recovery record")
+        previous = self._parts(journal.get("previous"))
+        next_parts = self._parts(journal.get("next"))
+        current = self.vault.get_password(self.service, "session") or ""
+        committed = hashlib.sha256(current.encode()).hexdigest() == journal["target_sha256"]
+        self._clear_parts(previous if committed else next_parts)
+        self.vault.delete_password(self.service + ":pending", "session")
+
+    def write(self, value):
+        if not value.isascii() or len(value) > PART_SIZE * MAX_PARTS:
+            raise ValueError("Secure session exceeds its storage limit")
+        self._recover()
+        previous = self.vault.get_password(self.service, "session")
+        old_parts = self._parts(previous)
+        new_parts = []
+        manifest = value
+        if len(value) > PART_SIZE:
+            record = {
+                "vault_format": 1,
+                "generation": secrets.token_hex(16),
+                "parts": (len(value) + PART_SIZE - 1) // PART_SIZE,
+                "sha256": hashlib.sha256(value.encode()).hexdigest(),
+            }
+            manifest = json.dumps(record)
+            new_parts = self._parts(manifest)
+        if new_parts or old_parts:
+            # A metadata-only journal in the same vault permits cleanup after process death.
+            self.vault.set_password(
+                self.service + ":pending",
+                "session",
+                json.dumps(
+                    {
+                        "previous": previous if old_parts else None,
+                        "next": manifest if new_parts else None,
+                        "target_sha256": hashlib.sha256(manifest.encode()).hexdigest(),
+                    }
+                ),
+            )
+        try:
+            for index, part in enumerate(new_parts):
+                self.vault.set_password(
+                    part, "session", value[index * PART_SIZE : (index + 1) * PART_SIZE]
+                )
+            # Publish the complete generation only after every fragment is in the OS vault.
+            self.vault.set_password(self.service, "session", manifest)
+        except Exception:
+            self._recover()
+            raise
+        self._recover()
+
+    def delete(self):
+        self._recover()
+        value = self.vault.get_password(self.service, "session")
+        self._clear_parts(self._parts(value))
+        if value is not None:
+            self.vault.delete_password(self.service, "session")

apizit_cli/errors.py

@@ -0,0 +1,19 @@
+"""Stable CLI exit and error contract."""
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_DENIED = 4
+EXIT_CONFLICT = 5
+EXIT_NETWORK = 6
+EXIT_TIMEOUT = 7
+EXIT_INTERRUPTED = 130
+
+
+class CliError(Exception):
+    def __init__(self, message, *, code="CLI_ERROR", exit_code=EXIT_FAILED, details=None):
+        super().__init__(message)
+        self.code = code
+        self.exit_code = exit_code
+        self.details = details or {}

apizit_cli/http.py

@@ -0,0 +1,162 @@
+"""One workspace-fenced HTTP transport for every CLI operation."""
+
+from __future__ import annotations
+
+import time
+from urllib.parse import quote
+
+import requests
+
+from apizit_cli.authentication import NativeSession
+from apizit_cli.errors import (
+    CliError,
+    EXIT_AUTH,
+    EXIT_CONFLICT,
+    EXIT_DENIED,
+    EXIT_NETWORK,
+    EXIT_TIMEOUT,
+    EXIT_USAGE,
+)
+
+
+def identifier(value):
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value) > 256
+        or any(ord(c) < 33 for c in value)
+    ):
+        raise CliError("Invalid resource identifier.", code="INVALID_IDENTIFIER", exit_code=2)
+    return quote(value, safe="")
+
+
+class PlatformClient:
+    def __init__(self, context, *, session=None, authentication=None):
+        self.context = context
+        self.http = session or requests.Session()
+        self.http.trust_env = False
+        self.auth = authentication or NativeSession(context.origin, http=self.http)
+        self.request_id = None
+
+    def request(
+        self,
+        method,
+        path,
+        *,
+        body=None,
+        query=None,
+        workspace=True,
+        authenticated=True,
+        idempotency_key=None,
+        timeout=30,
+    ):
+        if not path.startswith("/") or path.startswith("//") or "?" in path or "#" in path:
+            raise ValueError("Expected an API-relative path without a query.")
+        headers = {"Accept": "application/json"}
+        deadline = time.monotonic() + timeout
+        if workspace:
+            headers["X-Workspace-Id"] = self.context.require_workspace()
+        if authenticated:
+            headers["Authorization"] = "Bearer " + self.auth.token()
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        attempts = 3 if method == "GET" or (method == "POST" and idempotency_key) else 1
+        renewed = False
+        for attempt in range(attempts + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise CliError(
+                    "Local request time expired. A remote operation may still be running.",
+                    code="REQUEST_TIMEOUT",
+                    exit_code=EXIT_TIMEOUT,
+                )
+            try:
+                response = self.http.request(
+                    method,
+                    self.context.origin + path,
+                    headers=headers,
+                    json=body,
+                    params=query,
+                    timeout=(min(5, remaining / 2), remaining / 2),
+                    allow_redirects=False,
+                )
+            except (requests.ConnectionError, requests.Timeout):
+                if attempt + 1 < attempts:
+                    time.sleep(min(0.2 * (attempt + 1), max(0, deadline - time.monotonic())))
+                    continue
+                raise CliError(
+                    "Could not reach APIZIT. A submitted operation may still be running; reuse its idempotency key.",
+                    code="NETWORK_UNAVAILABLE",
+                    exit_code=EXIT_NETWORK,
+                ) from None
+            except requests.RequestException:
+                raise CliError(
+                    "Could not reach APIZIT.", code="NETWORK_UNAVAILABLE", exit_code=EXIT_NETWORK
+                ) from None
+            self.request_id = response.headers.get("X-Request-Id")
+            if (
+                response.status_code == 401
+                and authenticated
+                and not renewed
+                and not self.auth.injected_token
+            ):
+                headers["Authorization"] = "Bearer " + self.auth.token(force_refresh=True)
+                renewed = True
+                continue
+            if response.status_code in {502, 503, 504} and attempt + 1 < attempts:
+                time.sleep(min(0.2 * (attempt + 1), max(0, deadline - time.monotonic())))
+                continue
+            if response.status_code == 204:
+                return {}
+            try:
+                payload = response.json()
+                if not isinstance(payload, dict):
+                    raise ValueError()
+            except (ValueError, TypeError):
+                raise CliError(
+                    "APIZIT returned an invalid response.",
+                    code="INVALID_RESPONSE",
+                    exit_code=EXIT_NETWORK,
+                    details={"http_status": response.status_code, "request_id": self.request_id},
+                ) from None
+            if not 200 <= response.status_code < 300:
+                message = payload.get("error")
+                exit_code = {
+                    400: EXIT_USAGE,
+                    401: EXIT_AUTH,
+                    402: EXIT_DENIED,
+                    403: EXIT_DENIED,
+                    409: EXIT_CONFLICT,
+                    423: EXIT_DENIED,
+                    422: EXIT_USAGE,
+                    429: EXIT_DENIED,
+                    428: EXIT_USAGE,
+                }.get(response.status_code, EXIT_NETWORK if response.status_code >= 500 else 1)
+                raise CliError(
+                    message if isinstance(message, str) else "APIZIT rejected the request.",
+                    code=payload.get("code") or "HTTP_ERROR",
+                    exit_code=exit_code,
+                    details={
+                        "http_status": response.status_code,
+                        "request_id": self.request_id,
+                        "retry_after": response.headers.get("Retry-After"),
+                        **{
+                            key: payload[key]
+                            for key in (
+                                "profile_required",
+                                "required_fields",
+                                "action",
+                                "job_id",
+                                "scan_id",
+                                "deployment_id",
+                            )
+                            if key in payload
+                        },
+                    },
+                )
+            return payload
+        raise CliError(
+            "APIZIT authentication could not be renewed.",
+            code="LOGIN_REQUIRED",
+            exit_code=EXIT_AUTH,
+        )

apizit_cli/main.py

@@ -0,0 +1,164 @@
+"""Public executable: HTTP client only, with a stable machine output contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+
+from apizit_cli import __version__
+from apizit_cli.commands import COMMANDS, GLOBAL_OPTIONS
+from apizit_cli.configuration import ConfigurationError
+from apizit_cli.errors import CliError, EXIT_INTERRUPTED, EXIT_USAGE
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        # argparse can include argument values in its diagnostics. Keep those out of logs.
+        raise CliError(
+            "Invalid or missing command arguments. Run apizit <command> --help.",
+            code="INVALID_ARGUMENTS",
+            exit_code=EXIT_USAGE,
+        )
+
+
+def positive_float(value):
+    number = float(value)
+    if not math.isfinite(number) or number <= 0:
+        raise ValueError("Expected a positive finite number.")
+    return number
+
+
+def add_options(parser, options, *, global_options=False):
+    for option in options:
+        kwargs = {"help": option.help}
+        if option.action:
+            kwargs["action"] = option.action
+        elif option.value_type != "str":
+            kwargs["type"] = {"int": int, "positive_float": positive_float}[option.value_type]
+        if option.choices:
+            kwargs["choices"] = option.choices
+        if option.nargs:
+            kwargs["nargs"] = option.nargs
+        if option.flags[0].startswith("-"):
+            kwargs["default"] = argparse.SUPPRESS if global_options else option.default
+        parser.add_argument(*option.flags, **kwargs)
+
+
+def build_parser():
+    common = Parser(add_help=False)
+    add_options(common, GLOBAL_OPTIONS, global_options=True)
+    parser = Parser(
+        prog="apizit",
+        description="Launch Python as a managed public API. APIZIT development beta.",
+        parents=[common],
+        allow_abbrev=False,
+    )
+    parser.add_argument("--version", action="version", version=f"apizit {__version__}")
+    root = parser.add_subparsers(dest="command", required=True)
+    groups = {}
+    for command in COMMANDS:
+        words = command.path.split()
+        parent = root
+        if len(words) == 2:
+            if words[0] not in groups:
+                group = root.add_parser(
+                    words[0],
+                    parents=[common],
+                    allow_abbrev=False,
+                    help=f"Manage {words[0]} resources.",
+                )
+                groups[words[0]] = group.add_subparsers(dest="action", required=True)
+            parent = groups[words[0]]
+        leaf = parent.add_parser(
+            words[-1],
+            parents=[common],
+            allow_abbrev=False,
+            help=command.summary,
+            description=command.summary,
+        )
+        leaf.set_defaults(command_path=command.path)
+        add_options(leaf, command.options)
+    return parser
+
+
+def envelope(*, command, data=None, error=None, runner=None):
+    return {
+        "schema_version": 1,
+        "ok": error is None,
+        "command": command,
+        "data": data,
+        "error": (
+            {"code": error.code, "message": str(error), "details": error.details} if error else None
+        ),
+        "meta": {
+            "cli_version": __version__,
+            "workspace_id": runner.context.workspace_id if runner else None,
+            "request_id": runner.client.request_id if runner else None,
+        },
+    }
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    json_mode = "--json" in argv
+    runner = None
+    command = None
+    exit_code = 0
+    try:
+        args = build_parser().parse_args(argv)
+        json_mode = bool(getattr(args, "json", False))
+        command = args.command_path
+        from apizit_cli.operations import CommandRunner
+
+        runner = CommandRunner(args)
+        data = runner.run()
+        result = envelope(command=command, data=data, runner=runner)
+    except KeyboardInterrupt:
+        exit_code = EXIT_INTERRUPTED
+        error = CliError(
+            "Local observation interrupted. A remote operation may still be running.",
+            code="LOCAL_INTERRUPTED",
+            exit_code=EXIT_INTERRUPTED,
+            details=runner.tracking if runner else {},
+        )
+        result = envelope(command=command, error=error, runner=runner)
+    except CliError as error:
+        exit_code = error.exit_code
+        if runner:
+            error.details = {**runner.tracking, **error.details}
+        result = envelope(command=command, error=error, runner=runner)
+    except ConfigurationError as cause:
+        exit_code = EXIT_USAGE
+        error = CliError(str(cause), code="CONFIGURATION_INVALID", exit_code=EXIT_USAGE)
+        result = envelope(command=command, error=error, runner=runner)
+    except (OSError, UnicodeError):
+        exit_code = EXIT_USAGE
+        error = CliError(
+            "A local file or device could not be read or written.",
+            code="LOCAL_IO_ERROR",
+            exit_code=EXIT_USAGE,
+            details=runner.tracking if runner else {},
+        )
+        result = envelope(command=command, error=error, runner=runner)
+    except Exception:
+        exit_code = 1
+        error = CliError(
+            "The client could not complete this command. Use the request ID and client version when reporting it.",
+            code="CLIENT_UNEXPECTED_ERROR",
+            details=runner.tracking if runner else {},
+        )
+        result = envelope(command=command, error=error, runner=runner)
+    if json_mode:
+        print(json.dumps(result, ensure_ascii=True, separators=(",", ":")))
+    elif result["ok"]:
+        # JSON quoting prevents untrusted API names or logs from executing terminal escapes.
+        print(json.dumps(result["data"], ensure_ascii=True, indent=2))
+    else:
+        print(json.dumps(result["error"], ensure_ascii=True, indent=2), file=sys.stderr)
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())