codapact 0.1.0__py3-none-any.whl

codapact/loading.py

@@ -0,0 +1,121 @@
+"""Data-only loading and bounded, document-local JSON pointer resolution."""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, override
+
+import yaml
+from yaml.tokens import AliasToken, AnchorToken
+
+from codapact.errors import CodaError
+from codapact.net import MAX_BYTES, HttpTransport, Transport
+
+
+class UniqueLoader(yaml.SafeLoader):
+    """Reject ambiguous duplicate keys instead of accepting the last one."""
+
+    @override
+    def construct_mapping(self, node, deep=False):
+        keys = [self.construct_object(key, deep=deep) for key, _ in node.value]
+        if any(not isinstance(key, str) for key in keys) or len(set(keys)) != len(keys):
+            raise CodaError("mapping keys must be unique strings")
+        return super().construct_mapping(node, deep=deep)
+
+
+def parse(data: bytes) -> dict[str, Any]:
+    if len(data) > MAX_BYTES:
+        raise CodaError("document exceeds 2 MB limit")
+    try:
+
+        def unique_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+            result = dict(pairs)
+            if len(result) != len(pairs):
+                raise CodaError("mapping keys must be unique strings")
+            return result
+
+        try:
+            value = json.loads(data, object_pairs_hook=unique_pairs)
+        except json.JSONDecodeError:
+            if any(isinstance(token, (AliasToken, AnchorToken)) for token in yaml.scan(data)):
+                raise CodaError("YAML aliases and anchors are unsupported") from None
+            value = yaml.load(data, Loader=UniqueLoader)  # noqa: S506 -- SafeLoader subclass
+        count = 0
+
+        def visit(node: Any, depth: int) -> None:
+            nonlocal count
+            count += 1
+            if depth > 48 or count > 50_000:
+                raise CodaError("document complexity limit exceeded")
+            if isinstance(node, dict):
+                if any(not isinstance(k, str) for k in node):
+                    raise CodaError("all mapping keys must be strings")
+                for child in node.values():
+                    visit(child, depth + 1)
+            elif isinstance(node, list):
+                for child in node:
+                    visit(child, depth + 1)
+            elif node is not None and not isinstance(node, (str, int, float, bool)):
+                raise CodaError("only JSON-compatible values are supported")
+
+        visit(value, 0)
+        json.dumps(value, allow_nan=False)
+        if not isinstance(value, dict):
+            raise CodaError("document root must be an object")
+        return value
+    except (yaml.YAMLError, UnicodeError, ValueError, RecursionError):
+        raise CodaError("invalid JSON/YAML document") from None
+
+
+def load(source: str, *, transport: Transport | None = None) -> dict[str, Any]:
+    if source.startswith(("https://", "http://")):
+        response = (transport or HttpTransport()).send(
+            "GET", source, {"Accept": "application/json"}, None
+        )
+        if response.status != 200:
+            raise CodaError("contract download did not return HTTP 200")
+        return parse(response.body)
+    try:
+        with Path(source).open("rb") as handle:
+            return parse(handle.read(MAX_BYTES + 1))
+    except OSError:
+        raise CodaError("cannot read local document") from None
+
+
+def resolve(document: dict[str, Any]) -> dict[str, Any]:
+    """Resolve internal refs only; refuse recursion, siblings, and external fetches."""
+    budget = 0
+
+    def walk(node: Any, stack: tuple[str, ...] = (), depth: int = 0) -> Any:
+        nonlocal budget
+        budget += 1
+        if budget > 100_000 or depth > 48:
+            raise CodaError("reference expansion limit exceeded")
+        if isinstance(node, list):
+            return [walk(child, stack, depth + 1) for child in node]
+        if not isinstance(node, dict):
+            return node
+        if "$ref" in node:
+            ref = node["$ref"]
+            if len(node) != 1 or not isinstance(ref, str) or not ref.startswith("#/"):
+                raise CodaError("only document-local references without siblings are supported")
+            if "%" in ref or re.search(r"~(?:[^01]|$)", ref):
+                raise CodaError("unsupported URI-encoded reference or invalid JSON Pointer escape")
+            if ref in stack:
+                raise CodaError("recursive references are unsupported")
+            target: Any = document
+            try:
+                for token in ref[2:].split("/"):
+                    token = token.replace("~1", "/").replace("~0", "~")
+                    if isinstance(target, list):
+                        if not re.fullmatch(r"0|[1-9][0-9]*", token):
+                            raise ValueError
+                        target = target[int(token)]
+                    else:
+                        target = target[token]
+            except (KeyError, IndexError, TypeError, ValueError):
+                raise CodaError("unresolved internal reference") from None
+            return walk(target, (*stack, ref), depth + 1)
+        return {key: walk(child, stack, depth + 1) for key, child in node.items()}
+
+    return walk(document)

codapact/model.py

@@ -0,0 +1,83 @@
+"""Versioned source-neutral intermediate representation and plugin contracts."""
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Protocol
+
+from codapact.errors import CodaError
+
+API_VERSION = 1
+IR_VERSION = 1
+
+
+@dataclass(frozen=True)
+class Operation:
+    id: str
+    method: str
+    path: str
+    parameters: tuple[dict[str, Any], ...]
+    body: dict[str, Any] | None
+    body_required: bool
+    responses: dict[str, dict[str, Any] | None]
+    security: tuple[dict[str, list[str]], ...]
+    summary: str = ""
+
+
+@dataclass(frozen=True)
+class Contract:
+    title: str
+    base_url: str
+    operations: tuple[Operation, ...]
+    security_schemes: dict[str, dict[str, Any]]
+    types: dict[str, dict[str, Any]] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    version: int = IR_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class Translator(Protocol):
+    api_version: int
+    capabilities: frozenset[str]
+
+    def translate(self, document: dict[str, Any]) -> Contract: ...
+
+
+class Generator(Protocol):
+    api_version: int
+    requires: frozenset[str]
+
+    def generate(self, contract: Contract, package: str) -> dict[str, str]: ...
+
+
+class Registry:
+    """Explicit registration only. Config never imports or executes Python."""
+
+    def __init__(self) -> None:
+        self.translators: dict[str, Translator] = {}
+        self.generators: dict[str, Generator] = {}
+
+    def translator(self, name: str, plugin: Translator) -> None:
+        self._check(name, plugin.api_version, self.translators)
+        self.translators[name] = plugin
+
+    def generator(self, name: str, plugin: Generator) -> None:
+        self._check(name, plugin.api_version, self.generators)
+        self.generators[name] = plugin
+
+    @staticmethod
+    def _check(name: str, version: int, existing: dict[str, Any]) -> None:
+        if type(version) is not int or version != API_VERSION or name in existing:
+            raise CodaError("incompatible plugin API version or duplicate registration")
+
+    def negotiate(
+        self, source: str, targets: tuple[str, ...]
+    ) -> tuple[Translator, list[Generator]]:
+        try:
+            translator = self.translators[source]
+            generators = [self.generators[name] for name in targets]
+        except KeyError:
+            raise CodaError("unknown source or target plugin") from None
+        if any(not generator.requires <= translator.capabilities for generator in generators):
+            raise CodaError("plugin capabilities are incompatible")
+        return translator, generators

codapact/net.py

@@ -0,0 +1,100 @@
+"""Bounded HTTP transport with DNS pinning and no redirect following."""
+
+import http.client
+import ipaddress
+import socket
+import ssl
+from dataclasses import dataclass
+from typing import Protocol, cast
+from urllib.parse import SplitResult, urlsplit
+
+from codapact.errors import CodaError, TransportError
+
+MAX_BYTES = 2_000_000
+
+
+def validate_url(url: str, *, allow_query: bool = True) -> SplitResult:
+    """Reject ambiguous URL normalization before credentials can be attached."""
+    try:
+        if any(
+            character.isspace() or ord(character) < 32 or ord(character) == 127 for character in url
+        ):
+            raise ValueError
+        parts = urlsplit(url)
+        if (
+            parts.scheme not in {"http", "https"}
+            or parts.hostname is None
+            or parts.username is not None
+            or parts.password is not None
+            or parts.fragment
+            or not parts.path.isascii()
+            or not parts.query.isascii()
+            or (not allow_query and parts.query)
+            or parts.port == 0
+        ):
+            raise ValueError
+        return parts
+    except (ValueError, TypeError):
+        raise CodaError(
+            "URL must be unambiguous HTTP(S), without credentials or fragments"
+        ) from None
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    headers: dict[str, str]
+    body: bytes
+
+
+class Transport(Protocol):
+    """Implementations must not follow redirects or log credentials."""
+
+    def send(
+        self, method: str, url: str, headers: dict[str, str], body: bytes | None
+    ) -> Response: ...
+
+
+class HttpTransport:
+    """Single-request transport; private destinations require explicit opt-in."""
+
+    def __init__(self, *, allow_private: bool = False, timeout: float = 15) -> None:
+        if not 0 < timeout <= 120:
+            raise CodaError("timeout must be between 0 and 120 seconds")
+        self.allow_private = allow_private
+        self.timeout = timeout
+
+    def send(self, method: str, url: str, headers: dict[str, str], body: bytes | None) -> Response:
+        try:
+            parts = validate_url(url)
+            hostname = cast(str, parts.hostname)
+            port = parts.port or (443 if parts.scheme == "https" else 80)
+            addresses = socket.getaddrinfo(hostname, port, type=socket.SOCK_STREAM)
+            ips = [str(item[4][0]) for item in addresses]
+            if not ips or (
+                not self.allow_private and any(not ipaddress.ip_address(ip).is_global for ip in ips)
+            ):
+                raise CodaError("private network access requires explicit allow_private")
+            if parts.scheme == "http" and not self.allow_private:
+                raise CodaError("plaintext HTTP requires explicit allow_private")
+            connection = http.client.HTTPConnection(hostname, port, timeout=self.timeout)
+            # Resolve once, then connect to that exact address. TLS still checks the hostname.
+            sock = socket.create_connection((ips[0], port), timeout=self.timeout)
+            try:
+                if parts.scheme == "https":
+                    sock = ssl.create_default_context().wrap_socket(sock, server_hostname=hostname)
+                connection.sock = sock
+                target = (parts.path or "/") + ("?" + parts.query if parts.query else "")
+                connection.request(method, target, body, headers)
+                response = connection.getresponse()
+                data = response.read(MAX_BYTES + 1)
+                if len(data) > MAX_BYTES:
+                    raise TransportError("HTTP response exceeds 2 MB limit")
+                if 300 <= response.status < 400:
+                    raise TransportError("HTTP redirects are disabled")
+                return Response(response.status, dict(response.getheaders()), data)
+            finally:
+                connection.close()
+                sock.close()
+        except (OSError, ValueError, http.client.HTTPException):
+            raise TransportError("HTTP request failed; check URL, network, and TLS") from None

codapact/openapi.py

@@ -0,0 +1,294 @@
+"""Strict OpenAPI 3.0 translator for a deliberately bounded JSON API slice."""
+
+import keyword
+import re
+from typing import Any
+
+from jsonschema import Draft7Validator
+from jsonschema.exceptions import SchemaError
+
+from codapact.errors import CodaError
+from codapact.loading import resolve
+from codapact.model import Contract, Operation
+from codapact.net import validate_url
+
+IDENTIFIER = re.compile(r"[a-z][a-z0-9_]{0,79}\Z")
+SCHEMA_KEYS = {
+    "type",
+    "properties",
+    "required",
+    "items",
+    "additionalProperties",
+    "enum",
+    "nullable",
+    "description",
+    "title",
+    "default",
+    "example",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minProperties",
+    "maxProperties",
+}
+
+
+def normalized_schema(schema: Any) -> dict[str, Any]:
+    if not isinstance(schema, dict) or set(schema) - SCHEMA_KEYS:
+        raise CodaError("unsupported schema keyword; see supported OpenAPI subset")
+    result = dict(schema)
+    kind = result.get("type")
+    if not isinstance(kind, str) or kind not in {
+        "object",
+        "array",
+        "string",
+        "integer",
+        "number",
+        "boolean",
+    }:
+        raise CodaError("schemas require an explicit supported type")
+    if kind == "object":
+        properties = result.get("properties", {})
+        if not isinstance(properties, dict):
+            raise CodaError("properties must be an object")
+        result["properties"] = {key: normalized_schema(value) for key, value in properties.items()}
+        additional = result.get("additionalProperties", True)
+        if isinstance(additional, dict):
+            result["additionalProperties"] = normalized_schema(additional)
+        elif not isinstance(additional, bool):
+            raise CodaError("invalid additionalProperties")
+        if not set(result.get("required", [])) <= properties.keys():
+            raise CodaError("required fields must be declared properties")
+    if kind == "array":
+        result["items"] = normalized_schema(result.get("items"))
+    nullable = result.pop("nullable", False)
+    if not isinstance(nullable, bool):
+        raise CodaError("nullable must be boolean")
+    if nullable:
+        result["type"] = [kind, "null"]
+    try:
+        Draft7Validator.check_schema(result)
+    except SchemaError:
+        raise CodaError("invalid schema constraints") from None
+    return result
+
+
+def content_schema(item: dict[str, Any]) -> dict[str, Any] | None:
+    content = item.get("content", {})
+    if not content:
+        return None
+    if set(content) != {"application/json"}:
+        raise CodaError("only application/json bodies are supported")
+    if set(content["application/json"]) - {"schema", "example", "examples"}:
+        raise CodaError("unsupported media type feature")
+    return normalized_schema(content["application/json"].get("schema"))
+
+
+class OpenAPITranslator:
+    api_version = 1
+    capabilities = frozenset({"json-http-v1", "ir-v1"})
+
+    def translate(self, document: dict[str, Any]) -> Contract:
+        try:
+            return self._translate(resolve(document))
+        except (KeyError, TypeError, AttributeError, ValueError):
+            raise CodaError("malformed OpenAPI document") from None
+
+    def _translate(self, doc: dict[str, Any]) -> Contract:
+        if doc.get("openapi") not in {"3.0.0", "3.0.1", "3.0.2", "3.0.3"}:
+            raise CodaError("supported OpenAPI versions: 3.0.0 through 3.0.3")
+        if (
+            not isinstance(doc.get("info"), dict)
+            or not all(
+                isinstance(doc["info"].get(key), str) and doc["info"][key]
+                for key in ("title", "version")
+            )
+            or not isinstance(doc.get("paths"), dict)
+        ):
+            raise CodaError("OpenAPI requires info.title, info.version, and a paths object")
+        if doc.get("callbacks") or doc.get("webhooks"):
+            raise CodaError("callbacks and webhooks are unsupported")
+        servers = doc.get("servers", [])
+        if len(servers) != 1 or servers[0].get("variables"):
+            raise CodaError("exactly one server without variables is required")
+        base_url = servers[0]["url"].rstrip("/")
+        validate_url(base_url, allow_query=False)
+        schemes = doc.get("components", {}).get("securitySchemes", {})
+        for scheme in schemes.values():
+            if scheme.get("type") == "http" and scheme.get("scheme") in {"bearer", "basic"}:
+                continue
+            if scheme.get("type") == "apiKey" and scheme.get("in") == "header":
+                name = scheme.get("name", "")
+                if not re.fullmatch(r"[A-Za-z][A-Za-z0-9-]{0,79}", name):
+                    raise CodaError("invalid API key header name")
+                if name.lower() in {
+                    "host",
+                    "content-length",
+                    "transfer-encoding",
+                    "connection",
+                    "content-type",
+                    "accept",
+                    "expect",
+                    "te",
+                    "trailer",
+                    "upgrade",
+                    "proxy-authorization",
+                    "proxy-connection",
+                }:
+                    raise CodaError("unsafe API key header")
+                continue
+            raise CodaError("supported security: HTTP bearer/basic and header API key")
+        operations = []
+        names: set[str] = set()
+        for path, item in doc["paths"].items():
+            if (
+                not path.startswith("/")
+                or path.startswith("//")
+                or "?" in path
+                or "#" in path
+                or "\\" in path
+                or "%" in path
+                or any(ord(c) < 32 for c in path)
+                or not path.isascii()
+                or "{" in re.sub(r"\{[A-Za-z][A-Za-z0-9_-]*\}", "", path)
+                or "}" in re.sub(r"\{[A-Za-z][A-Za-z0-9_-]*\}", "", path)
+            ):
+                raise CodaError("invalid operation path")
+            if any(part in {".", ".."} for part in path.split("/")):
+                raise CodaError("path traversal is unsupported")
+            if item.get("servers") or item.get("$ref"):
+                raise CodaError("path-specific servers are unsupported")
+            for method, operation in item.items():
+                if method in {"parameters", "summary", "description"} or method.startswith("x-"):
+                    continue
+                if method not in {"get", "post", "put", "patch", "delete", "head", "options"}:
+                    raise CodaError("unsupported path item field")
+                if operation.get("callbacks") or operation.get("servers"):
+                    raise CodaError("callbacks and operation-specific servers are unsupported")
+                name = operation.get("operationId", "")
+                if not IDENTIFIER.fullmatch(name) or keyword.iskeyword(name) or name in names:
+                    raise CodaError(
+                        "operationId must be unique lowercase snake_case (max 80 characters)"
+                    )
+                names.add(name)
+                parameters: dict[tuple[str, str], dict[str, Any]] = {}
+                for parameter_list in (item.get("parameters", []), operation.get("parameters", [])):
+                    pairs = [
+                        (p["in"], p["name"].lower() if p["in"] == "header" else p["name"])
+                        for p in parameter_list
+                    ]
+                    if len(set(pairs)) != len(pairs):
+                        raise CodaError("duplicate parameter declarations")
+                for parameter in [*item.get("parameters", []), *operation.get("parameters", [])]:
+                    if not isinstance(parameter.get("required", False), bool):
+                        raise CodaError("parameter required must be boolean")
+                    location = parameter["in"]
+                    if location not in {"path", "query", "header"}:
+                        raise CodaError("only scalar path/query/header parameters are supported")
+                    if set(parameter) - {
+                        "name",
+                        "in",
+                        "required",
+                        "schema",
+                        "description",
+                        "deprecated",
+                        "style",
+                        "explode",
+                    }:
+                        raise CodaError("unsupported parameter feature")
+                    expected = "form" if location == "query" else "simple"
+                    if parameter.get("style", expected) != expected or parameter.get(
+                        "explode", False
+                    ):
+                        raise CodaError("unsupported parameter serialization")
+                    schema = normalized_schema(parameter["schema"])
+                    if schema["type"] not in {"string", "integer", "number", "boolean"}:
+                        raise CodaError("parameters must be non-null scalar types")
+                    pname = parameter["name"]
+                    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,79}", pname):
+                        raise CodaError("unsupported parameter name")
+                    if location == "header" and pname.lower() in {
+                        "authorization",
+                        "host",
+                        "content-length",
+                        "transfer-encoding",
+                        "connection",
+                        "accept",
+                        "content-type",
+                        *[s.get("name", "").lower() for s in schemes.values()],
+                    }:
+                        raise CodaError("reserved/auth headers must use runtime configuration")
+                    if location == "path" and parameter.get("required") is not True:
+                        raise CodaError("path parameters must be required")
+                    parameters[location, pname.lower() if location == "header" else pname] = {
+                        "name": pname,
+                        "in": location,
+                        "required": parameter.get("required", False),
+                        "schema": schema,
+                    }
+                if {p["name"] for p in parameters.values() if p["in"] == "path"} != set(
+                    re.findall(r"\{([^{}]+)\}", path)
+                ):
+                    raise CodaError("path placeholders and parameters must match")
+                if len({p["name"] for p in parameters.values()}) != len(parameters):
+                    raise CodaError("parameter names must be unique across locations")
+                responses = {}
+                for status, response in operation["responses"].items():
+                    if status != "default" and not re.fullmatch(r"[1-5][0-9]{2}", status):
+                        raise CodaError("response keys must be exact HTTP status codes or default")
+                    if response.get("links") or response.get("headers"):
+                        raise CodaError(
+                            "response links and declared response headers are unsupported"
+                        )
+                    schema = content_schema(response)
+                    if schema is not None and (method == "head" or status in {"204", "205"}):
+                        raise CodaError("HEAD, 204, and 205 responses cannot declare a JSON body")
+                    responses[status] = schema
+                if not any(key.startswith("2") for key in responses):
+                    raise CodaError("an explicit successful response is required")
+                security = operation.get("security", doc.get("security", []))
+                if not isinstance(security, list):
+                    raise CodaError("security must be an OR list of AND requirement objects")
+                for alternative in security:
+                    if not isinstance(alternative, dict) or any(
+                        key not in schemes or scopes != [] for key, scopes in alternative.items()
+                    ):
+                        raise CodaError("invalid security requirement or unsupported OAuth scopes")
+                body = operation.get("requestBody", {})
+                if not isinstance(body.get("required", False), bool):
+                    raise CodaError("request body required must be boolean")
+                if "requestBody" in operation and content_schema(body) is None:
+                    raise CodaError("request body must declare JSON content")
+                if "requestBody" in operation and method in {"get", "head"}:
+                    raise CodaError("GET and HEAD request bodies are unsupported")
+                operations.append(
+                    Operation(
+                        name,
+                        method.upper(),
+                        path,
+                        tuple(parameters.values()),
+                        content_schema(body),
+                        body.get("required", False),
+                        responses,
+                        tuple(security),
+                        str(operation.get("summary", "")),
+                    )
+                )
+        if not operations:
+            raise CodaError("contract must contain operations")
+        types = {
+            name: normalized_schema(schema)
+            for name, schema in doc.get("components", {}).get("schemas", {}).items()
+        }
+        return Contract(
+            str(doc["info"]["title"]),
+            base_url,
+            tuple(sorted(operations, key=lambda op: op.id)),
+            schemes,
+            types,
+            {"source_format": "openapi-3.0", "pagination": "manual", "streaming": False},
+        )