codapact 0.1.0__py3-none-any.whl

codapact/profiles.py

@@ -0,0 +1,171 @@
+"""Portable runtime discovery and explicit, replaceable credential storage."""
+
+import base64
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any, Protocol
+
+from codapact.errors import AuthError, CodaError
+from codapact.loading import parse
+from codapact.runtime import EnvironmentAuth, config, validate
+from codapact.values import merge, slug_name
+
+
+def validate_profile(profile: dict[str, Any]) -> dict[str, Any]:
+    validate(
+        profile,
+        {
+            "type": "object",
+            "additionalProperties": False,
+            "required": ["version", "slug", "config_directory", "defaults"],
+            "properties": {
+                "version": {"type": "integer", "const": 1},
+                "slug": {"type": "string"},
+                "config_directory": {"type": ["string", "null"]},
+                "defaults": {"type": "object"},
+            },
+        },
+        "invalid runtime profile",
+    )
+    slug_name(profile["slug"])
+    directory = profile["config_directory"]
+    if directory is not None and (
+        not directory
+        or any(ord(c) < 32 for c in directory)
+        or not (Path(directory).is_absolute() or directory == "~" or directory.startswith("~/"))
+    ):
+        raise CodaError("runtime config directory must be absolute or start with ~/")
+    config(profile["defaults"])
+    if "auth" in profile["defaults"]:
+        raise CodaError("generated defaults cannot contain auth configuration")
+    return profile
+
+
+def config_directory(profile: dict[str, Any], explicit: str | None = None) -> Path:
+    validate_profile(profile)
+    if explicit is not None:
+        return Path(explicit).expanduser().absolute()
+    if profile["config_directory"] is not None:
+        return Path(profile["config_directory"]).expanduser()
+    root = os.environ.get("XDG_CONFIG_HOME", "")
+    base = Path(root) if root and Path(root).is_absolute() else Path.home() / ".config"
+    return base / str(profile["slug"])
+
+
+def read_file(path: Path, *, optional: bool = False, json_only: bool = False) -> dict[str, Any]:
+    """Bounded regular local data; never follow links or modify permissions."""
+    try:
+        if any(p.is_symlink() or p.is_junction() for p in (path, *path.parents)):
+            raise CodaError("configuration links and junctions are unsupported")
+        if not stat.S_ISREG(path.stat().st_mode):
+            raise CodaError("configuration must be a regular file")
+        with path.open("rb") as handle:
+            if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
+                raise CodaError("configuration must be a regular file")
+            data = handle.read(65_537)
+        if len(data) > 65_536:
+            raise CodaError("configuration file exceeds size limit")
+        if json_only:
+            try:
+                json.loads(data)
+            except (ValueError, UnicodeError):
+                raise CodaError("configuration requires JSON data") from None
+        return parse(data)
+    except FileNotFoundError:
+        if optional:
+            return {}
+        raise CodaError("configuration file does not exist") from None
+    except OSError:
+        raise CodaError("cannot read configuration file") from None
+
+
+class CredentialStore(Protocol):
+    """Explicit dependency injection boundary for future keyring providers."""
+
+    def get(self, name: str) -> dict[str, str] | None: ...
+
+
+class JsonFileStore:
+    def __init__(self, path: Path, *, optional: bool = False) -> None:
+        document = read_file(path, optional=optional, json_only=True)
+        if document == {} and optional and not path.exists():
+            self.entries: dict[str, dict[str, str]] = {}
+            return
+        validate(
+            document,
+            {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["version", "credentials"],
+                "properties": {
+                    "version": {"type": "integer", "const": 1},
+                    "credentials": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "object",
+                            "additionalProperties": {"type": "string"},
+                        },
+                    },
+                },
+            },
+            "invalid auth file",
+        )
+        self.entries = document["credentials"]
+        for entry in self.entries.values():
+            if set(entry) not in (
+                {"value"},
+                {"username", "password"},
+                {"env"},
+                {"username_env", "password_env"},
+            ):
+                raise AuthError("invalid auth credential fields")
+
+    def get(self, name: str) -> dict[str, str] | None:
+        return self.entries.get(name)
+
+
+class StoredAuth:
+    def __init__(self, store: CredentialStore, fallback: EnvironmentAuth | None = None) -> None:
+        self.store = store
+        self.fallback = fallback or EnvironmentAuth()
+
+    def headers(self, name: str, scheme: dict[str, Any]) -> dict[str, str]:
+        entry = self.store.get(name)
+        if entry is None:
+            return self.fallback.headers(name, scheme)
+        if set(entry) in ({"env"}, {"username_env", "password_env"}):
+            return EnvironmentAuth({name: entry}).headers(name, scheme)
+        if any(
+            not value or any(ord(c) < 32 or ord(c) == 127 for c in value)
+            for value in entry.values()
+        ):
+            raise AuthError("required credential is missing or invalid")
+        if scheme["type"] == "apiKey" or scheme.get("scheme") == "bearer":
+            if set(entry) != {"value"}:
+                raise AuthError("credential type does not match security scheme")
+            return (
+                {scheme["name"]: entry["value"]}
+                if scheme["type"] == "apiKey"
+                else {"Authorization": "Bearer " + entry["value"]}
+            )
+        if set(entry) != {"username", "password"} or ":" in entry["username"]:
+            raise AuthError("invalid basic auth credential")
+        token = base64.b64encode((entry["username"] + ":" + entry["password"]).encode()).decode()
+        return {"Authorization": "Basic " + token}
+
+
+def runtime_settings(
+    profile: dict[str, Any], directory: str | None, path: str | None, overrides: dict[str, Any]
+) -> tuple[dict[str, Any], Path]:
+    root = config_directory(profile, directory)
+    if path is not None and "://" in path:
+        raise CodaError("runtime configuration must be local")
+    document = read_file(
+        Path(path) if path is not None else root / "config.json", optional=path is None
+    )
+    if path is None and "auth" in document:
+        raise CodaError("put credentials in auth.json; config.json is ordinary configuration")
+    settings = config(merge(merge(profile["defaults"], document), overrides))
+    return settings, root

codapact/project.py

@@ -0,0 +1,173 @@
+"""Orchestration and ownership-aware regeneration."""
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+from dataclasses import replace
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from codapact import __version__
+from codapact.errors import CodaError
+from codapact.generation import ArgparseGenerator, PythonGenerator, canonical, package_name
+from codapact.loading import load
+from codapact.model import Registry
+from codapact.net import Transport
+from codapact.openapi import OpenAPITranslator
+
+MANIFEST = ".codapact-manifest.json"
+
+
+def default_registry() -> Registry:
+    registry = Registry()
+    registry.translator("openapi", OpenAPITranslator())
+    registry.generator("python", PythonGenerator())
+    registry.generator("argparse", ArgparseGenerator())
+    return registry
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _safe_path(root: Path, relative: str) -> Path:
+    parts = PurePosixPath(relative).parts
+    if (
+        not parts
+        or relative != PurePosixPath(relative).as_posix()
+        or not re.fullmatch(r"[A-Za-z0-9_./-]+", relative)
+        or relative.startswith("/")
+        or "\\" in relative
+        or ":" in relative
+        or any(part in {".", ".."} or part.endswith((".", " ")) for part in parts)
+        or any(
+            re.fullmatch(r"(?i:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?", part) for part in parts
+        )
+        or relative == MANIFEST
+    ):
+        raise CodaError("unsafe generated path")
+    path = root.joinpath(*parts)
+    for parent in (path, *path.parents):
+        if parent.is_symlink() or parent.is_junction():
+            raise CodaError("symlinks and junctions are unsupported in generation paths")
+        if parent != path and parent.exists() and not parent.is_dir():
+            raise CodaError("generated path parent is not a directory")
+    return path
+
+
+def write_project(root: Path, files: dict[str, str]) -> None:
+    root = root.absolute()
+    _safe_path(root, "probe")
+    if root.exists() and not root.is_dir():
+        raise CodaError("output must be a directory")
+    manifest = root / MANIFEST
+    if manifest.is_symlink():
+        raise CodaError("manifest cannot be a symlink")
+    previous = {}
+    if manifest.exists():
+        try:
+            state = json.loads(manifest.read_text("utf-8"))
+            if (
+                state["version"] != 1
+                or not isinstance(state["files"], dict)
+                or any(
+                    not isinstance(k, str)
+                    or not isinstance(v, str)
+                    or not re.fullmatch(r"[0-9a-f]{64}", v)
+                    for k, v in state["files"].items()
+                )
+            ):
+                raise ValueError
+            previous = state["files"]
+        except (ValueError, KeyError, OSError):
+            raise CodaError("invalid ownership manifest") from None
+    encoded = {name: value.encode("utf-8") for name, value in files.items()}
+    names = {name.casefold() for name in encoded}
+    if len(names) != len(encoded) or any(
+        parent.as_posix().casefold() in names
+        for name in encoded
+        for parent in PurePosixPath(name).parents
+    ):
+        raise CodaError("generated files have conflicting paths")
+    for name in previous.keys() | encoded.keys():
+        path = _safe_path(root, name)
+        if path.exists():
+            if (
+                not path.is_file()
+                or name not in previous
+                or digest(path.read_bytes()) != previous[name]
+            ):
+                raise CodaError("regeneration refused: existing file is unowned or modified")
+    root.mkdir(parents=True, exist_ok=True)
+    # Each file is atomically replaced. Manifest commits last; interrupted multi-file
+    # updates fail closed on the next attempt instead of claiming transactional safety.
+    for name, data in sorted(encoded.items()):
+        path = _safe_path(root, name)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        _atomic(path, data)
+    for name in previous.keys() - encoded.keys():
+        _safe_path(root, name).unlink(missing_ok=True)
+    _atomic(
+        manifest,
+        canonical(
+            {
+                "version": 1,
+                "generator": f"codapact/{__version__}",
+                "files": {name: digest(data) for name, data in encoded.items()},
+            }
+        ).encode(),
+    )
+
+
+def _atomic(path: Path, data: bytes) -> None:
+    fd, temporary = tempfile.mkstemp(prefix=".coda-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def generate(
+    source: str,
+    output: Path,
+    *,
+    package: str,
+    registry: Registry | None = None,
+    source_plugin: str = "openapi",
+    targets: tuple[str, ...] = ("python", "argparse"),
+    cli_definition: dict[str, Any] | None = None,
+    transport: Transport | None = None,
+    profile: dict[str, Any] | None = None,
+) -> None:
+    package_name(package)
+    translator, generators = (registry or default_registry()).negotiate(source_plugin, targets)
+    contract = translator.translate(load(source, transport=transport))
+    if contract.version != 1:
+        raise CodaError("unsupported IR version")
+    if profile is not None:
+        from codapact.profiles import validate_profile
+
+        profile = validate_profile(profile)
+        contract = replace(
+            contract,
+            metadata={
+                **contract.metadata,
+                "codapact.runtime": profile,
+                "codapact.cli": profile["slug"],
+            },
+        )
+    files: dict[str, str] = {}
+    for generator in generators:
+        generated = (
+            generator.generate_with_definition(contract, package, cli_definition)
+            if isinstance(generator, ArgparseGenerator)
+            else generator.generate(contract, package)
+        )
+        if files.keys() & generated.keys():
+            raise CodaError("generators have conflicting file ownership")
+        files.update(generated)
+    write_project(output, files)

codapact/runtime.py

@@ -0,0 +1,299 @@
+"""Reusable execution, authentication, policy, and response validation layers."""
+
+import base64
+import json
+import math
+import os
+import re
+from collections.abc import Mapping
+from typing import Any, Protocol
+from urllib.parse import quote, urlencode
+
+from jsonschema import Draft7Validator
+
+from codapact.errors import ApiError, AuthError, CodaError, PolicyError, ResponseError
+from codapact.net import HttpTransport, Transport, validate_url
+from codapact.values import merge
+
+
+class Unset:
+    """An omitted body, distinct from an explicitly supplied JSON null."""
+
+
+UNSET = Unset()
+
+
+def validate(value: Any, schema: dict[str, Any], message: str) -> None:
+    visited = 0
+
+    def json_value(node: Any, depth: int = 0) -> None:
+        nonlocal visited
+        visited += 1
+        if depth > 48 or visited > 50_000:
+            raise CodaError(message)
+        if isinstance(node, dict):
+            if any(not isinstance(key, str) for key in node):
+                raise CodaError(message)
+            for child in node.values():
+                json_value(child, depth + 1)
+        elif isinstance(node, list):
+            for child in node:
+                json_value(child, depth + 1)
+        elif isinstance(node, float) and not math.isfinite(node):
+            raise CodaError(message)
+        elif node is not None and not isinstance(node, (str, int, float, bool)):
+            raise CodaError(message)
+
+    json_value(value)
+    if not Draft7Validator(schema).is_valid(value):
+        raise CodaError(message)
+
+
+def map_types(value: Any, schema: dict[str, Any]) -> Any:
+    """Map validated JSON integer numbers to actual Python integers, recursively."""
+    kind = schema["type"]
+    if value is None:
+        return None
+    if kind == "integer" or kind == ["integer", "null"]:
+        return int(value)
+    if isinstance(value, list):
+        return [map_types(item, schema["items"]) for item in value]
+    if isinstance(value, dict):
+        properties = schema.get("properties", {})
+        additional = schema.get("additionalProperties", True)
+        return {
+            key: map_types(item, properties[key])
+            if key in properties
+            else map_types(item, additional)
+            if isinstance(additional, dict)
+            else item
+            for key, item in value.items()
+        }
+    return value
+
+
+class AuthProvider(Protocol):
+    """Return scheme-specific headers or raise AuthError if unavailable."""
+
+    def headers(self, name: str, scheme: dict[str, Any]) -> dict[str, str]: ...
+
+
+class AuthorizationPolicy(Protocol):
+    """Client-side guard only. The server remains the authorization authority."""
+
+    def authorize(self, operation: Mapping[str, Any]) -> None: ...
+
+
+class OperationPolicy:
+    def __init__(self, *, allow: list[str] | None = None, deny: list[str] | None = None) -> None:
+        self.allow = None if allow is None else frozenset(allow)
+        self.deny = frozenset(deny or [])
+
+    def authorize(self, operation: Mapping[str, Any]) -> None:
+        name = operation["id"]
+        if name in self.deny or (self.allow is not None and name not in self.allow):
+            raise PolicyError(f"client policy denies operation {name}")
+
+
+class EnvironmentAuth:
+    """Credentials are resolved at execution time, never written into generated files."""
+
+    def __init__(self, settings: dict[str, dict[str, str]] | None = None) -> None:
+        self.settings = settings or {}
+
+    @staticmethod
+    def _secret(entry: dict[str, str], key: str) -> str:
+        reference = entry.get(key, "")
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", reference):
+            raise AuthError("auth requires an environment variable reference")
+        value = os.environ.get(reference)
+        if value is None or value == "" or any(ord(c) < 32 or ord(c) == 127 for c in value):
+            raise AuthError("required credential is missing or invalid")
+        return value
+
+    def headers(self, name: str, scheme: dict[str, Any]) -> dict[str, str]:
+        entry = self.settings.get(name, {})
+        if scheme["type"] == "apiKey":
+            return {scheme["name"]: self._secret(entry, "env")}
+        if scheme["scheme"] == "bearer":
+            return {"Authorization": "Bearer " + self._secret(entry, "env")}
+        username = self._secret(entry, "username_env")
+        if ":" in username:
+            raise AuthError("basic auth username cannot contain a colon")
+        token = base64.b64encode(
+            (username + ":" + self._secret(entry, "password_env")).encode()
+        ).decode()
+        return {"Authorization": "Basic " + token}
+
+
+def config(settings: dict[str, Any] | None) -> dict[str, Any]:
+    settings = {} if settings is None else settings
+    schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {
+            "version": {"const": 1},
+            "base_url": {"type": "string"},
+            "allow_private": {"type": "boolean"},
+            "timeout": {"type": "number", "exclusiveMinimum": 0, "maximum": 120},
+            "auth": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "properties": {
+                        key: {"type": "string"} for key in ("env", "username_env", "password_env")
+                    },
+                },
+            },
+            "policy": {
+                "type": "object",
+                "additionalProperties": False,
+                "properties": {
+                    key: {"type": "array", "items": {"type": "string"}} for key in ("allow", "deny")
+                },
+            },
+        },
+    }
+    validate(settings, schema, "invalid runtime configuration")
+    return settings
+
+
+class ClientBase:
+    """Base for generated clients; use explicit objects to install custom hooks."""
+
+    def __init__(
+        self,
+        document: dict[str, Any],
+        *,
+        settings: dict[str, Any] | None = None,
+        transport: Transport | None = None,
+        auth: AuthProvider | None = None,
+        policy: AuthorizationPolicy | None = None,
+    ) -> None:
+        profile = document.get("metadata", {}).get("codapact.runtime")
+        if profile is not None:
+            from codapact.profiles import validate_profile
+
+            validate_profile(profile)
+            settings = merge(profile["defaults"], settings or {})
+        settings = config(settings)
+        if document.get("version") != 1:
+            raise CodaError("unsupported IR version")
+        self._operations = {operation["id"]: operation for operation in document["operations"]}
+        self._schemes = document["security_schemes"]
+        self._base_url = settings.get("base_url", document["base_url"]).rstrip("/")
+        validate_url(self._base_url, allow_query=False)
+        self._transport = transport or HttpTransport(
+            allow_private=settings.get("allow_private", False), timeout=settings.get("timeout", 15)
+        )
+        self._auth = auth or EnvironmentAuth(settings.get("auth"))
+        self._policy = policy or OperationPolicy(**settings.get("policy", {}))
+
+    def _security(self, operation: dict[str, Any]) -> dict[str, str]:
+        # OpenAPI: alternatives are OR; schemes within an alternative are AND.
+        if not operation["security"]:
+            return {}
+        for alternative in operation["security"]:
+            result: dict[str, str] = {}
+            try:
+                for name in alternative:
+                    scheme = self._schemes[name]
+                    headers = self._auth.headers(name, scheme)
+                    expected = scheme["name"] if scheme["type"] == "apiKey" else "Authorization"
+                    if (
+                        not headers
+                        or expected.lower() not in {key.lower() for key in headers}
+                        or any(not value for value in headers.values())
+                    ):
+                        raise AuthError(
+                            "auth provider did not satisfy the required security scheme"
+                        )
+                    for key, value in headers.items():
+                        if key.lower() in {k.lower() for k in result}:
+                            raise AuthError("AND security schemes conflict on a header")
+                        result[key] = value
+                return result
+            except AuthError:
+                continue
+        raise AuthError("no complete security alternative has usable credentials")
+
+    def _execute(
+        self, name: str, parameters: Mapping[str, Any] | None = None, body: Any = UNSET
+    ) -> Any:
+        operation = self._operations[name]
+        self._policy.authorize(operation)
+        values = dict(parameters or {})
+        definitions = operation["parameters"]
+        if values.keys() - {parameter["name"] for parameter in definitions}:
+            raise CodaError("unknown request parameter")
+        path = operation["path"]
+        query = []
+        headers = {"Accept": "application/json"}
+        for parameter in definitions:
+            key = parameter["name"]
+            if key not in values:
+                if parameter["required"]:
+                    raise CodaError(f"missing required parameter {key}")
+                continue
+            value = values[key]
+            validate(value, parameter["schema"], f"invalid parameter {key}")
+            value = map_types(value, parameter["schema"])
+            rendered = str(value).lower() if isinstance(value, bool) else str(value)
+            if parameter["in"] == "path":
+                # Reject dot-only segments, which intermediaries can normalize even when escaped.
+                if rendered in {".", ".."}:
+                    raise CodaError("dot path parameters are unsupported")
+                path = path.replace("{" + key + "}", quote(rendered, safe=""))
+            elif parameter["in"] == "query":
+                query.append((key, rendered))
+            else:
+                headers[key] = rendered
+        payload = None
+        if body is not UNSET:
+            if operation["body"] is None:
+                raise CodaError("operation does not accept a request body")
+            validate(body, operation["body"], "invalid request body")
+            body = map_types(body, operation["body"])
+            try:
+                payload = json.dumps(body, allow_nan=False).encode()
+            except (ValueError, TypeError):
+                raise CodaError("request body must be JSON compatible") from None
+            headers["Content-Type"] = "application/json"
+        elif operation["body_required"]:
+            raise CodaError("request body is required")
+        headers.update(self._security(operation))
+        for key, value in headers.items():
+            if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]*", key) or any(
+                character in value for character in ("\r", "\n", "\x00")
+            ):
+                raise CodaError("invalid request header")
+        url = self._base_url + path + ("?" + urlencode(query) if query else "")
+        response = self._transport.send(operation["method"], url, headers, payload)
+        if not 200 <= response.status < 300:
+            raise ApiError(response.status, name)
+        responses = operation["responses"]
+        status = str(response.status)
+        if status not in responses:
+            raise ResponseError("undeclared successful response status")
+        schema = responses[status]
+        if schema is None:
+            if response.body:
+                raise ResponseError("expected an empty response body")
+            return None
+        content_type = next(
+            (v for k, v in response.headers.items() if k.lower() == "content-type"), ""
+        )
+        if content_type.split(";")[0].strip().lower() != "application/json":
+            raise ResponseError("expected application/json response")
+        try:
+
+            def reject_constant(value: str) -> None:
+                raise ValueError("non-JSON numeric constant")
+
+            result = json.loads(response.body, parse_constant=reject_constant)
+            validate(result, schema, "response does not match the declared schema")
+            result = map_types(result, schema)
+        except (ValueError, UnicodeError, CodaError):
+            raise ResponseError("response does not match the declared JSON schema") from None
+        return result