runspec-webops-core 0.1.0__py3-none-any.whl

runspec_webops_core/__init__.py

@@ -0,0 +1,67 @@
+"""runspec-webops-core — pure-Python HTTPS/TLS + web-endpoint helpers.
+
+This package has **no dependency on runspec** and ships **no runspec.toml and no
+entry points**, so installing it exposes the helper functions for import without
+surfacing any runnables (it is invisible to ``runspec local`` / ``runspec serve``
+discovery). ``runspec-linux`` and ``runspec-windows`` both depend on it and wrap
+each helper in a cross-platform runnable; a private (e.g. Nexus-hosted) package
+can instead import these helpers directly and ship its own runnables.
+
+Everything is stdlib only (``ssl`` / ``socket`` / ``http.client``). Each function
+returns plain data and *raises* on failure (see ``runspec_webops_core.errors``).
+"""
+
+from runspec_webops_core.dns import resolve
+from runspec_webops_core.errors import ConnectError, ResolveError, WebopsCoreError
+from runspec_webops_core.http import (
+    classify,
+    fetch_body,
+    fetch_headers,
+    probe,
+    trace_redirects,
+)
+from runspec_webops_core.openapi import (
+    SpecError,
+    describe_operation,
+    load_document,
+    parse_document,
+    summarize_spec,
+)
+from runspec_webops_core.tls import (
+    CertInfo,
+    TlsPeer,
+    cert_status,
+    chain_report,
+    connect_peer,
+    days_until,
+    leaf_report,
+)
+
+__all__ = [
+    # errors
+    "WebopsCoreError",
+    "ConnectError",
+    "ResolveError",
+    "SpecError",
+    # tls
+    "CertInfo",
+    "TlsPeer",
+    "connect_peer",
+    "leaf_report",
+    "chain_report",
+    "days_until",
+    "cert_status",
+    # http
+    "probe",
+    "classify",
+    "fetch_headers",
+    "fetch_body",
+    "trace_redirects",
+    # dns
+    "resolve",
+    # openapi
+    "load_document",
+    "parse_document",
+    "summarize_spec",
+    "describe_operation",
+]

runspec_webops_core/dns.py

@@ -0,0 +1,65 @@
+"""DNS resolution — forward (A/AAAA) and reverse (PTR) via stdlib ``socket``."""
+
+from __future__ import annotations
+
+import socket
+
+from runspec_webops_core.errors import ResolveError
+
+
+def _is_ip(value: str) -> bool:
+    for family in (socket.AF_INET, socket.AF_INET6):
+        try:
+            socket.inet_pton(family, value)
+            return True
+        except OSError:
+            continue
+    return False
+
+
+def _reverse(ip: str) -> list[str]:
+    """PTR names for an address. Returns ``[]`` when there is no reverse record."""
+    try:
+        name, aliases, _ = socket.gethostbyaddr(ip)
+    except OSError:
+        return []
+    return [name, *aliases]
+
+
+def resolve(host: str, want_reverse: bool = False) -> dict:
+    """Resolve ``host``.
+
+    A bare IP yields its PTR records. A name yields its A/AAAA addresses and
+    canonical name; with ``want_reverse`` each address is also reverse-resolved.
+    Raises :class:`ResolveError` when the name cannot be resolved.
+    """
+    if _is_ip(host):
+        return {"host": host, "is_ip": True, "reverse": {host: _reverse(host)}}
+
+    try:
+        infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP, flags=socket.AI_CANONNAME)
+    except socket.gaierror as e:
+        raise ResolveError(f"could not resolve {host!r}: {e}") from e
+
+    addresses: list[dict] = []
+    seen: set[tuple[int, str]] = set()
+    canonical = ""
+    for family, _type, _proto, canonname, sockaddr in infos:
+        if canonname:
+            canonical = canonname
+        ip = str(sockaddr[0])
+        key = (int(family), ip)
+        if key in seen:
+            continue
+        seen.add(key)
+        addresses.append({"ip": ip, "family": "ipv6" if family == socket.AF_INET6 else "ipv4"})
+
+    result: dict = {
+        "host": host,
+        "is_ip": False,
+        "addresses": addresses,
+        "canonical_name": canonical or None,
+    }
+    if want_reverse:
+        result["reverse"] = {entry["ip"]: _reverse(entry["ip"]) for entry in addresses}
+    return result

runspec_webops_core/errors.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by the webops helpers.
+
+The wrappers in ``runspec-linux`` / ``runspec-windows`` catch these to reproduce
+the CLI/agent behaviour (a connect failure exits differently from a bad result).
+"""
+
+from __future__ import annotations
+
+
+class WebopsCoreError(Exception):
+    """Base class for all runspec-webops-core failures."""
+
+
+class ConnectError(WebopsCoreError):
+    """A TLS/HTTP connection could not be established (refused, timed out, reset)."""
+
+
+class ResolveError(WebopsCoreError):
+    """A DNS name could not be resolved."""

runspec_webops_core/http.py

@@ -0,0 +1,224 @@
+"""HTTP(S) endpoint probing — stdlib ``http.client`` / ``ssl`` only.
+
+A single request is issued and its status / timing / a few headers are captured;
+the body is drained, not buffered. ``classify`` and the security-header analysis
+are pure. Redirects are *not* followed by :func:`probe` — :func:`trace_redirects`
+walks them explicitly so each hop is visible.
+"""
+
+from __future__ import annotations
+
+import http.client
+import socket
+import ssl
+import time
+from urllib.parse import urljoin, urlsplit
+
+from runspec_webops_core.errors import ConnectError
+
+_USER_AGENT = "runspec-webops"
+
+# Response security headers worth surfacing — present value or flagged as missing.
+SECURITY_HEADERS: dict[str, str] = {
+    "strict-transport-security": "strict_transport_security",
+    "content-security-policy": "content_security_policy",
+    "x-frame-options": "x_frame_options",
+    "x-content-type-options": "x_content_type_options",
+    "referrer-policy": "referrer_policy",
+    "permissions-policy": "permissions_policy",
+}
+
+
+def classify(status: int) -> str:
+    """Bucket an HTTP status code. Pure."""
+    if 200 <= status < 300:
+        return "ok"
+    if 300 <= status < 400:
+        return "redirect"
+    if 400 <= status < 500:
+        return "client-error"
+    if 500 <= status < 600:
+        return "server-error"
+    return "unknown"
+
+
+def _request(url: str, timeout: float, method: str, insecure: bool) -> tuple[int, str, list[tuple[str, str]], float]:
+    """Issue one request and return ``(status, reason, headers, elapsed_ms)``.
+
+    Raises :class:`ConnectError` on any transport-level failure.
+    """
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https"):
+        raise ConnectError(f"unsupported URL scheme: {parts.scheme!r} (expected http or https)")
+    if not parts.hostname:
+        raise ConnectError(f"no host in URL: {url!r}")
+
+    is_https = parts.scheme == "https"
+    port = parts.port or (443 if is_https else 80)
+    path = parts.path or "/"
+    if parts.query:
+        path = f"{path}?{parts.query}"
+
+    if is_https:
+        ctx = ssl.create_default_context()
+        if insecure:
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+        conn: http.client.HTTPConnection = http.client.HTTPSConnection(parts.hostname, port, timeout=timeout, context=ctx)
+    else:
+        conn = http.client.HTTPConnection(parts.hostname, port, timeout=timeout)
+
+    start = time.monotonic()
+    try:
+        conn.request(method, path, headers={"User-Agent": _USER_AGENT, "Accept": "*/*"})
+        resp = conn.getresponse()
+        resp.read()  # drain so the socket can be reused/closed cleanly
+        elapsed = round((time.monotonic() - start) * 1000, 1)
+        return resp.status, resp.reason or "", resp.getheaders(), elapsed
+    except (OSError, TimeoutError, ssl.SSLError, http.client.HTTPException, socket.gaierror) as e:
+        raise ConnectError(f"request to {url} failed: {e}") from e
+    finally:
+        conn.close()
+
+
+def fetch_body(url: str, timeout: float = 15.0, insecure: bool = False, max_bytes: int = 10_000_000, max_redirects: int = 5) -> tuple[int, str]:
+    """GET a URL and return ``(status, body_text)``, following redirects.
+
+    Used to retrieve documents (e.g. an OpenAPI spec). The body is size-capped so
+    a runaway endpoint can't exhaust memory. Raises :class:`ConnectError` on a
+    transport failure or when the body exceeds ``max_bytes``.
+    """
+    current = url
+    seen: set[str] = set()
+    for _ in range(max_redirects + 1):
+        parts = urlsplit(current)
+        if parts.scheme not in ("http", "https"):
+            raise ConnectError(f"unsupported URL scheme: {parts.scheme!r} (expected http or https)")
+        if not parts.hostname:
+            raise ConnectError(f"no host in URL: {current!r}")
+        if current in seen:
+            raise ConnectError(f"redirect loop while fetching {url}")
+        seen.add(current)
+
+        is_https = parts.scheme == "https"
+        port = parts.port or (443 if is_https else 80)
+        path = parts.path or "/"
+        if parts.query:
+            path = f"{path}?{parts.query}"
+
+        if is_https:
+            ctx = ssl.create_default_context()
+            if insecure:
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
+            conn: http.client.HTTPConnection = http.client.HTTPSConnection(parts.hostname, port, timeout=timeout, context=ctx)
+        else:
+            conn = http.client.HTTPConnection(parts.hostname, port, timeout=timeout)
+
+        try:
+            conn.request("GET", path, headers={"User-Agent": _USER_AGENT, "Accept": "application/json, application/yaml;q=0.9, */*;q=0.8"})
+            resp = conn.getresponse()
+            if 300 <= resp.status < 400:
+                location = resp.getheader("location")
+                resp.read()
+                if location:
+                    current = urljoin(current, location)
+                    continue
+            raw = resp.read(max_bytes + 1)
+            if len(raw) > max_bytes:
+                raise ConnectError(f"response from {current} exceeds {max_bytes} bytes")
+            charset = "utf-8"
+            ctype = resp.getheader("content-type") or ""
+            if "charset=" in ctype:
+                charset = ctype.split("charset=", 1)[1].split(";")[0].strip() or "utf-8"
+            return resp.status, raw.decode(charset, errors="replace")
+        except (OSError, TimeoutError, ssl.SSLError, http.client.HTTPException, socket.gaierror) as e:
+            raise ConnectError(f"request to {current} failed: {e}") from e
+        finally:
+            conn.close()
+
+    raise ConnectError(f"too many redirects while fetching {url}")
+
+
+def _header(headers: list[tuple[str, str]], name: str) -> str | None:
+    target = name.lower()
+    for key, value in headers:
+        if key.lower() == target:
+            return value
+    return None
+
+
+def probe(url: str, timeout: float = 10.0, method: str = "GET", insecure: bool = False) -> dict:
+    """Single-request probe: status, timing, ``server`` / ``location`` headers."""
+    status, reason, headers, elapsed = _request(url, timeout, method, insecure)
+    return {
+        "url": url,
+        "status": status,
+        "status_text": reason,
+        "time_ms": elapsed,
+        "server": _header(headers, "server"),
+        "location": _header(headers, "location"),
+        "class": classify(status),
+    }
+
+
+def fetch_headers(url: str, timeout: float = 10.0, method: str = "HEAD", insecure: bool = False) -> dict:
+    """Fetch response headers and report on the security headers (present/missing)."""
+    status, reason, headers, elapsed = _request(url, timeout, method, insecure)
+    header_map = {key.lower(): value for key, value in headers}
+    security: dict[str, str | None] = {}
+    missing: list[str] = []
+    for raw, friendly in SECURITY_HEADERS.items():
+        value = header_map.get(raw)
+        security[friendly] = value
+        if value is None:
+            missing.append(raw)
+    return {
+        "url": url,
+        "status": status,
+        "status_text": reason,
+        "time_ms": elapsed,
+        "class": classify(status),
+        "headers": dict(header_map),
+        "security": security,
+        "missing_security_headers": missing,
+    }
+
+
+def trace_redirects(url: str, timeout: float = 10.0, max_hops: int = 10, insecure: bool = False) -> dict:
+    """Walk the redirect chain, recording each hop until a non-3xx or ``max_hops``."""
+    hops: list[dict] = []
+    seen: set[str] = set()
+    current = url
+    final_status = 0
+    for _ in range(max_hops + 1):
+        if current in seen:
+            hops.append({"url": current, "status": None, "status_text": "redirect loop", "location": None, "time_ms": 0.0})
+            break
+        seen.add(current)
+        status, reason, headers, elapsed = _request(current, timeout, "GET", insecure)
+        location = _header(headers, "location")
+        hops.append(
+            {
+                "url": current,
+                "status": status,
+                "status_text": reason,
+                "location": location,
+                "time_ms": elapsed,
+            }
+        )
+        final_status = status
+        if not (300 <= status < 400) or not location:
+            break
+        current = urljoin(current, location)
+    else:
+        # Loop exhausted without a terminal response.
+        hops[-1]["status_text"] = (hops[-1]["status_text"] or "") + " (max hops reached)"
+
+    return {
+        "url": url,
+        "hops": hops,
+        "final_url": hops[-1]["url"] if hops else url,
+        "final_status": final_status,
+        "redirect_count": max(len(hops) - 1, 0),
+    }

runspec_webops_core/openapi.py

@@ -0,0 +1,317 @@
+"""OpenAPI / Swagger spec reading — condense an API's current shape to bounded JSON.
+
+The point: let an agent (or operator) see the *live* shape of an internal API —
+its operations, parameters, and request/response schemas — so it can write or
+update the runspec runnables that call it, and re-check when the API drifts. The
+output is small and bounded (a map, not the raw spec), so it stays cheap to feed
+to a model.
+
+JSON specs (FastAPI ``/openapi.json``, springdoc ``/v3/api-docs``,
+``swagger.json``) parse with the stdlib. YAML specs need the optional ``pyyaml``
+extra. Both OpenAPI 3.x and Swagger 2.0 are understood. The fetch/read is the
+only I/O; summarisation is pure.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from runspec_webops_core.errors import WebopsCoreError
+from runspec_webops_core.http import fetch_body
+
+# HTTP methods an OpenAPI path item may carry as operations.
+_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+
+# Defensive caps so the summary stays bounded regardless of spec size.
+MAX_OPERATIONS = 300
+_MAX_PROPERTIES = 60
+_MAX_ENUM = 20
+_MAX_SCHEMA_DEPTH = 3
+
+
+class SpecError(WebopsCoreError):
+    """The spec could not be fetched, read, or parsed."""
+
+
+# ── loading ───────────────────────────────────────────────────────────────────
+
+
+def load_document(source: str, timeout: float = 15.0, insecure: bool = False) -> dict:
+    """Fetch (URL) or read (file path) a spec and parse it into a dict."""
+    if source.startswith(("http://", "https://")):
+        status, body = fetch_body(source, timeout=timeout, insecure=insecure)
+        if status >= 400:
+            raise SpecError(f"fetching {source} returned HTTP {status}")
+    else:
+        path = Path(source)
+        if not path.is_file():
+            raise SpecError(f"no such spec file: {source}")
+        body = path.read_text(encoding="utf-8", errors="replace")
+    return parse_document(body)
+
+
+def parse_document(text: str) -> dict:
+    """Parse spec text as JSON, falling back to YAML when ``pyyaml`` is present."""
+    text = text.strip()
+    if not text:
+        raise SpecError("spec document is empty")
+    try:
+        data: Any = json.loads(text)
+    except json.JSONDecodeError:
+        data = _parse_yaml(text)
+    if not isinstance(data, dict):
+        raise SpecError("spec did not parse to an object")
+    if "openapi" not in data and "swagger" not in data:
+        raise SpecError("document is not an OpenAPI/Swagger spec (no 'openapi' or 'swagger' key)")
+    return data
+
+
+def _parse_yaml(text: str) -> Any:
+    try:
+        import yaml  # type: ignore[import-untyped]  # noqa: PLC0415 — optional dependency, only needed for YAML specs
+    except ModuleNotFoundError as e:
+        raise SpecError(
+            "spec is not JSON and PyYAML is not installed — install the 'yaml' extra (pip install runspec-webops-core[yaml]) or point at the JSON spec endpoint (e.g. /openapi.json or /v3/api-docs)"
+        ) from e
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise SpecError(f"could not parse spec as JSON or YAML: {e}") from e
+
+
+# ── $ref resolution ───────────────────────────────────────────────────────────
+
+
+def _resolve_ref(doc: dict, ref: str) -> Any:
+    """Resolve a local JSON-pointer ``$ref`` (``#/...``); returns None if missing."""
+    if not ref.startswith("#/"):
+        return None
+    node: Any = doc
+    for part in ref[2:].split("/"):
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, dict) and part in node:
+            node = node[part]
+        else:
+            return None
+    return node
+
+
+def _deref(doc: dict, schema: Any, depth: int = 0) -> Any:
+    """Follow a single ``$ref`` (bounded), returning the referenced node."""
+    if not isinstance(schema, dict) or "$ref" not in schema:
+        return schema
+    if depth > _MAX_SCHEMA_DEPTH + 2:
+        return schema
+    target = _resolve_ref(doc, schema["$ref"])
+    if target is None:
+        return schema
+    return _deref(doc, target, depth + 1)
+
+
+# ── schema summarising ────────────────────────────────────────────────────────
+
+
+def _ref_name(ref: str) -> str:
+    return ref.rsplit("/", 1)[-1]
+
+
+def short_type(doc: dict, schema: Any, depth: int = 0) -> str:
+    """A one-token type label for a schema (``string``, ``array<Order>``, ``User``)."""
+    if isinstance(schema, dict) and "$ref" in schema:
+        return _ref_name(schema["$ref"])
+    schema = _deref(doc, schema, depth)
+    if not isinstance(schema, dict):
+        return "any"
+    kind = schema.get("type")
+    if kind == "array":
+        items = schema.get("items", {})
+        if isinstance(items, dict) and "$ref" in items:
+            return f"array<{_ref_name(items['$ref'])}>"
+        return f"array<{short_type(doc, items, depth + 1)}>"
+    fmt = schema.get("format")
+    if isinstance(kind, str):
+        return f"{kind}({fmt})" if fmt else kind
+    if "properties" in schema:
+        return "object"
+    return "any"
+
+
+def summarize_schema(doc: dict, schema: Any, depth: int = 0) -> dict:
+    """A bounded structural summary of a schema (type, properties, required, …)."""
+    if isinstance(schema, dict) and "$ref" in schema and depth >= _MAX_SCHEMA_DEPTH:
+        return {"$ref": _ref_name(schema["$ref"])}
+    resolved = _deref(doc, schema, depth)
+    if not isinstance(resolved, dict):
+        return {}
+
+    out: dict = {}
+    if isinstance(resolved.get("type"), str):
+        out["type"] = resolved["type"]
+    if "format" in resolved:
+        out["format"] = resolved["format"]
+    if "enum" in resolved and isinstance(resolved["enum"], list):
+        out["enum"] = resolved["enum"][:_MAX_ENUM]
+    if resolved.get("type") == "array" and "items" in resolved and depth < _MAX_SCHEMA_DEPTH:
+        out["items"] = summarize_schema(doc, resolved["items"], depth + 1)
+
+    props = resolved.get("properties")
+    if isinstance(props, dict):
+        if depth < _MAX_SCHEMA_DEPTH:
+            out["properties"] = {name: short_type(doc, sub, depth + 1) for name, sub in list(props.items())[:_MAX_PROPERTIES]}
+            if len(props) > _MAX_PROPERTIES:
+                out["properties_truncated"] = True
+        out.setdefault("type", "object")
+        if isinstance(resolved.get("required"), list):
+            out["required"] = resolved["required"]
+    return out
+
+
+# ── operations ────────────────────────────────────────────────────────────────
+
+
+def _iter_operations(doc: dict) -> Iterator[tuple[str, str, dict, list]]:
+    """Yield ``(path, METHOD, operation, shared_parameters)`` for every operation."""
+    paths = doc.get("paths")
+    if not isinstance(paths, dict):
+        return
+    for path, item in paths.items():
+        if not isinstance(item, dict):
+            continue
+        shared = item.get("parameters", []) if isinstance(item.get("parameters"), list) else []
+        for method in _METHODS:
+            op = item.get(method)
+            if isinstance(op, dict):
+                yield path, method.upper(), op, shared
+
+
+def _servers(doc: dict) -> list[str]:
+    if isinstance(doc.get("servers"), list):
+        return [s["url"] for s in doc["servers"] if isinstance(s, dict) and isinstance(s.get("url"), str)]
+    # Swagger 2.0: host + basePath + schemes.
+    host = doc.get("host")
+    if not host:
+        return []
+    base = doc.get("basePath", "") or ""
+    raw_schemes = doc.get("schemes")
+    schemes = raw_schemes if isinstance(raw_schemes, list) else ["https"]
+    return [f"{scheme}://{host}{base}" for scheme in schemes]
+
+
+def summarize_spec(doc: dict, *, tag: str | None = None, path_filter: str | None = None, max_operations: int = MAX_OPERATIONS) -> dict:
+    """Overview: API info, servers, and a bounded list of operations."""
+    info = doc.get("info", {}) if isinstance(doc.get("info"), dict) else {}
+    operations: list[dict] = []
+    total = 0
+    for path, method, op, _shared in _iter_operations(doc):
+        if tag is not None and tag not in (op.get("tags") or []):
+            continue
+        if path_filter is not None and path_filter not in path:
+            continue
+        total += 1
+        if len(operations) < max_operations:
+            summary = op.get("summary") or (op.get("description") or "")[:120] or None
+            operations.append(
+                {
+                    "method": method,
+                    "path": path,
+                    "operation_id": op.get("operationId"),
+                    "summary": summary,
+                    "tags": op.get("tags") or [],
+                }
+            )
+    return {
+        "title": info.get("title"),
+        "version": info.get("version"),
+        "spec_version": doc.get("openapi") or doc.get("swagger"),
+        "servers": _servers(doc),
+        "operation_count": total,
+        "returned": len(operations),
+        "truncated": total > len(operations),
+        "operations": operations,
+    }
+
+
+def _find_operation(doc: dict, operation_id: str | None, path: str | None, method: str | None) -> tuple[str, str, dict, list] | None:
+    want_method = method.upper() if method else None
+    for p, m, op, shared in _iter_operations(doc):
+        if operation_id is not None and op.get("operationId") == operation_id:
+            return p, m, op, shared
+        if path is not None and p == path and (want_method is None or m == want_method):
+            return p, m, op, shared
+    return None
+
+
+def _parameter(doc: dict, raw: Any) -> dict | None:
+    raw = _deref(doc, raw)
+    if not isinstance(raw, dict):
+        return None
+    # OpenAPI 3 nests the type under `schema`; Swagger 2 puts `type` on the param.
+    schema = raw.get("schema")
+    if schema is None and "type" in raw:
+        schema = {"type": raw["type"], **({"format": raw["format"]} if "format" in raw else {})}
+    return {
+        "name": raw.get("name"),
+        "in": raw.get("in"),
+        "required": bool(raw.get("required")),
+        "description": raw.get("description"),
+        "type": short_type(doc, schema or {}),
+        "schema": summarize_schema(doc, schema) if schema else {},
+    }
+
+
+def _request_body(doc: dict, op: dict) -> dict | None:
+    rb = op.get("requestBody")
+    if not isinstance(rb, dict):
+        return None
+    rb = _deref(doc, rb)
+    content = rb.get("content") if isinstance(rb.get("content"), dict) else {}
+    out: dict = {"required": bool(rb.get("required")), "content_types": list(content.keys()), "schema": None}
+    for ctype, media in content.items():
+        if isinstance(media, dict) and "schema" in media:
+            out["selected_content_type"] = ctype
+            out["schema"] = summarize_schema(doc, media["schema"])
+            break
+    return out
+
+
+def _responses(doc: dict, op: dict) -> list[dict]:
+    out: list[dict] = []
+    raw_responses = op.get("responses")
+    responses = raw_responses if isinstance(raw_responses, dict) else {}
+    for code, resp in responses.items():
+        resp = _deref(doc, resp) if isinstance(resp, dict) else {}
+        schema = None
+        content = resp.get("content")
+        if isinstance(content, dict):
+            for media in content.values():
+                if isinstance(media, dict) and "schema" in media:
+                    schema = summarize_schema(doc, media["schema"])
+                    break
+        elif "schema" in resp:  # Swagger 2.0
+            schema = summarize_schema(doc, resp["schema"])
+        out.append({"status": str(code), "description": resp.get("description"), "schema": schema})
+    return out
+
+
+def describe_operation(doc: dict, *, operation_id: str | None = None, path: str | None = None, method: str | None = None) -> dict:
+    """Drill into one operation: parameters, request body, and responses (schemas resolved)."""
+    match = _find_operation(doc, operation_id, path, method)
+    if match is None:
+        target = operation_id or (f"{(method or '').upper()} {path}".strip() if path else None) or "(none given)"
+        raise SpecError(f"operation not found: {target}")
+    p, m, op, shared = match
+    parameters = [param for raw in [*shared, *(op.get("parameters") or [])] if (param := _parameter(doc, raw)) is not None]
+    return {
+        "method": m,
+        "path": p,
+        "operation_id": op.get("operationId"),
+        "summary": op.get("summary"),
+        "description": op.get("description"),
+        "tags": op.get("tags") or [],
+        "parameters": parameters,
+        "request_body": _request_body(doc, op),
+        "responses": _responses(doc, op),
+    }

runspec_webops_core/tls.py

@@ -0,0 +1,270 @@
+"""TLS certificate + connection inspection — stdlib ``ssl`` / ``socket`` only.
+
+The inspection connection deliberately disables verification (``CERT_NONE``): a
+cert *checker* must still complete the handshake against an expired, self-signed
+or otherwise untrusted endpoint in order to report on it. The trust result is
+captured separately by a second, *verifying* connection and surfaced via
+``authorized`` / ``authorization_error`` rather than raising.
+
+The network I/O is confined to :func:`connect_peer`; the reporting functions
+below are pure so they can be unit-tested without a socket.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import socket
+import ssl
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from runspec_webops_core.errors import ConnectError
+
+# Certificate freshness buckets.
+OK = "ok"
+EXPIRING = "expiring"
+EXPIRED = "expired"
+
+# ── data model ────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class CertInfo:
+    """One certificate's parsed fields plus its SHA-256 fingerprint."""
+
+    subject: str
+    issuer: str
+    valid_from: str
+    valid_to: str
+    alt_names: list[str] = field(default_factory=list)
+    serial_number: str = ""
+    fingerprint_sha256: str = ""
+    self_signed: bool = False
+
+
+@dataclass
+class TlsPeer:
+    """The result of a single TLS inspection connection."""
+
+    chain: list[CertInfo]
+    protocol: str | None
+    cipher_name: str | None
+    cipher_version: str | None
+    authorized: bool
+    authorization_error: str | None
+
+    @property
+    def leaf(self) -> CertInfo | None:
+        return self.chain[0] if self.chain else None
+
+
+# ── pure reporting ────────────────────────────────────────────────────────────
+
+
+def days_until(not_after: str, now: float | None = None) -> int:
+    """Whole days until an X.509 ``notAfter`` string (``'Jun  4 23:59:59 2026 GMT'``).
+
+    Negative when already expired. Raises ``ValueError`` when unparseable.
+    """
+    expiry = ssl.cert_time_to_seconds(not_after)
+    if now is None:
+        now = datetime.now(timezone.utc).timestamp()
+    return int((expiry - now) // 86_400)
+
+
+def cert_status(days_remaining: int, warn_days: int) -> str:
+    """Bucket a certificate by days-to-expiry. Pure."""
+    if days_remaining < 0:
+        return EXPIRED
+    if days_remaining <= warn_days:
+        return EXPIRING
+    return OK
+
+
+def _rdn_get(name: tuple, key: str) -> str:
+    """Pull a value out of an ``ssl`` RDN structure (tuple of relative-DN sets)."""
+    for rdn in name or ():
+        for pair in rdn:
+            if len(pair) == 2 and pair[0] == key:
+                return str(pair[1])
+    return ""
+
+
+def _common_name(name: tuple) -> str:
+    return _rdn_get(name, "commonName")
+
+
+def _issuer_label(name: tuple) -> str:
+    return _rdn_get(name, "commonName") or _rdn_get(name, "organizationName")
+
+
+def _alt_names(san: tuple | None) -> list[str]:
+    """Flatten an ``ssl`` ``subjectAltName`` tuple into a list of DNS names."""
+    return [str(value) for (kind, value) in (san or ()) if kind == "DNS"]
+
+
+def cert_info_from_ssl(info: dict, der: bytes) -> CertInfo:
+    """Build a :class:`CertInfo` from an ``ssl`` cert dict plus the DER bytes.
+
+    ``info`` is the shape returned by ``getpeercert()`` / ``Certificate.get_info()``.
+    ``self_signed`` is decided structurally (subject == issuer) rather than by a
+    trust check, so it holds for an inspection-only connection.
+    """
+    subject = _common_name(info.get("subject", ()))
+    issuer = _issuer_label(info.get("issuer", ()))
+    return CertInfo(
+        subject=subject,
+        issuer=issuer,
+        valid_from=str(info.get("notBefore", "")),
+        valid_to=str(info.get("notAfter", "")),
+        alt_names=_alt_names(info.get("subjectAltName")),
+        serial_number=str(info.get("serialNumber", "")),
+        fingerprint_sha256=_fingerprint(der),
+        self_signed=info.get("subject", ()) == info.get("issuer", ()),
+    )
+
+
+def _fingerprint(der: bytes) -> str:
+    """Colon-separated uppercase SHA-256 of a DER certificate (OpenSSL style)."""
+    hexed = hashlib.sha256(der).hexdigest().upper()
+    return ":".join(hexed[i : i + 2] for i in range(0, len(hexed), 2))
+
+
+def leaf_report(peer: TlsPeer, warn_days: int, now: float | None = None) -> dict:
+    """The cert-check view: leaf cert fields + freshness status + trust result."""
+    leaf = peer.leaf
+    if leaf is None:
+        raise ConnectError("no peer certificate was presented")
+    try:
+        days = days_until(leaf.valid_to, now)
+        status = cert_status(days, warn_days)
+    except ValueError:
+        days, status = -1, EXPIRED
+    return {
+        "subject": leaf.subject,
+        "issuer": leaf.issuer,
+        "valid_from": leaf.valid_from,
+        "valid_to": leaf.valid_to,
+        "days_remaining": days,
+        "status": status,
+        "alt_names": leaf.alt_names,
+        "serial_number": leaf.serial_number,
+        "fingerprint_sha256": leaf.fingerprint_sha256,
+        "authorized": peer.authorized,
+        "authorization_error": peer.authorization_error,
+    }
+
+
+def chain_report(peer: TlsPeer, now: float | None = None) -> list[dict]:
+    """The cert-chain view: one entry per cert, leaf → … → root."""
+    out: list[dict] = []
+    for link in peer.chain:
+        try:
+            days = days_until(link.valid_to, now)
+        except ValueError:
+            days = -1
+        out.append(
+            {
+                "subject": link.subject,
+                "issuer": link.issuer,
+                "valid_to": link.valid_to,
+                "days_remaining": days,
+                "self_signed": link.self_signed,
+            }
+        )
+    return out
+
+
+# ── network I/O ───────────────────────────────────────────────────────────────
+
+
+def _peer_chain(ssock: ssl.SSLSocket) -> list[CertInfo]:
+    """Return the server-presented certificate chain (leaf first).
+
+    Prefers the public ``SSLSocket.get_unverified_chain()`` (Python 3.13+),
+    falls back to the underlying ``_sslobj`` method (3.10–3.12), and finally to
+    the leaf-only certificate via ``getpeercert`` when neither is available.
+    """
+    getter = getattr(ssock, "get_unverified_chain", None)
+    if getter is None:
+        sslobj = getattr(ssock, "_sslobj", None)
+        getter = getattr(sslobj, "get_unverified_chain", None) if sslobj is not None else None
+
+    if getter is not None:
+        try:
+            raw = getter()
+        except Exception:
+            raw = None
+        if raw:
+            out: list[CertInfo] = []
+            for cert in raw:
+                der = ssl.PEM_cert_to_DER_cert(cert.public_bytes())
+                out.append(cert_info_from_ssl(cert.get_info(), der))
+            return out
+
+    # Fallback: only the leaf is recoverable on this interpreter.
+    leaf_der = ssock.getpeercert(binary_form=True)
+    if not leaf_der:
+        return []
+    return [cert_info_from_ssl(_decode_der(leaf_der), leaf_der)]
+
+
+def _decode_der(der: bytes) -> dict:
+    """Parse a DER certificate into the ``getpeercert`` dict via the stdlib decoder."""
+    pem = ssl.DER_cert_to_PEM_cert(der)
+    with tempfile.NamedTemporaryFile("w", suffix=".pem", delete=False) as fh:
+        fh.write(pem)
+        path = fh.name
+    try:
+        import _ssl  # noqa: PLC0415 — stdlib helper, imported lazily for the fallback path
+
+        return dict(_ssl._test_decode_cert(path))  # type: ignore[attr-defined]
+    finally:
+        Path(path).unlink(missing_ok=True)
+
+
+def _verify_trust(host: str, port: int, servername: str, timeout: float) -> tuple[bool, str | None]:
+    """Second connection with full verification — captures the trust verdict."""
+    ctx = ssl.create_default_context()
+    try:
+        with socket.create_connection((host, port), timeout=timeout) as sock, ctx.wrap_socket(sock, server_hostname=servername):
+            return True, None
+    except ssl.SSLCertVerificationError as e:
+        return False, getattr(e, "verify_message", None) or str(e)
+    except ssl.SSLError as e:
+        return False, str(e)
+    except (OSError, TimeoutError) as e:
+        # The unverified connection already succeeded, so a failure here is the
+        # trust handshake itself (e.g. a TLS alert), not unreachability.
+        return False, str(e)
+
+
+def connect_peer(host: str, port: int = 443, timeout: float = 10.0, servername: str | None = None) -> TlsPeer:
+    """Open a TLS connection and capture the cert chain, protocol, cipher, trust.
+
+    Raises :class:`ConnectError` only when the endpoint is unreachable — an
+    untrusted / expired certificate is reported, not raised.
+    """
+    sni = servername or host
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    try:
+        with socket.create_connection((host, port), timeout=timeout) as sock, ctx.wrap_socket(sock, server_hostname=sni) as ssock:
+            protocol = ssock.version()
+            cipher = ssock.cipher()
+            chain = _peer_chain(ssock)
+    except (OSError, TimeoutError, ssl.SSLError) as e:
+        raise ConnectError(f"connection to {host}:{port} failed: {e}") from e
+
+    authorized, auth_error = _verify_trust(host, port, sni, timeout)
+    return TlsPeer(
+        chain=chain,
+        protocol=protocol,
+        cipher_name=cipher[0] if cipher else None,
+        cipher_version=cipher[1] if cipher else None,
+        authorized=authorized,
+        authorization_error=auth_error,
+    )

runspec_webops_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: runspec-webops-core
+Version: 0.1.0
+Summary: Pure-Python HTTPS/TLS certificate + web-endpoint helpers — the importable core behind the runspec web runnables (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'

runspec_webops_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+runspec_webops_core/__init__.py,sha256=0Ps89jzfI58c4GCIkIvJIlhH7HsU9YaC6w4C0KODWqs,1739
+runspec_webops_core/dns.py,sha256=eogx6Wej8zMnc4bMaIDUD27i8BVpcXLR6xnWIo7Urv0,2011
+runspec_webops_core/errors.py,sha256=Ihv-Z8JIMHVJ06r8BSBoY3d5Q8MPAqpJimALlgT4FFI,550
+runspec_webops_core/http.py,sha256=lVUYP8MMPZlGE88UEj3fqg9tykcXHLwxJu930M_T9lA,8687
+runspec_webops_core/openapi.py,sha256=fegjPJRdV0C0D9nZrWY5nbF9Vs71Beb2ZaXaZZxGpBY,13087
+runspec_webops_core/tls.py,sha256=7GEmEPv_Zj2sr64Fq1fQ1zYN2C9OowkksvE0jx3dkAc,9884
+runspec_webops_core-0.1.0.dist-info/METADATA,sha256=E5ee_6uY8qvpX9VxcRd8_bPMLFgeA5JEp7_0NTECNb4,535
+runspec_webops_core-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runspec_webops_core-0.1.0.dist-info/RECORD,,

runspec_webops_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any