runspec-webops-core 0.1.0__tar.gz

runspec_webops_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_webops_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# runspec-webops-core Changelog
+
+## [0.1.0] — 2026-06-22
+
+Initial release.
+
+Pure-Python HTTPS/TLS + web-endpoint helpers — the importable logic core behind
+the cross-platform web runnables in `runspec-linux` and `runspec-windows`. Stdlib
+only (`ssl` / `socket` / `http.client`); **no `runspec` dependency, no
+`runspec.toml`, and no entry points**, so it surfaces zero runnables and stays
+invisible to `runspec local` / `runspec serve` discovery.
+
+Public API (every function returns plain data and raises on failure — see
+`runspec_webops_core.errors`):
+
+- **TLS** — `connect_peer(host, port, timeout)` opens an inspection connection
+  (verification disabled, so it still reports on expired/self-signed endpoints)
+  and a second verifying connection for the trust verdict; `leaf_report`,
+  `chain_report`, `days_until`, `cert_status` are the pure reporting helpers.
+  The certificate chain is read via `SSLSocket.get_unverified_chain()` (Python
+  3.13+), the underlying `_sslobj` method on 3.10–3.12, or the leaf-only
+  fallback when neither is available.
+- **HTTP** — `probe` (single request, no redirect following), `classify`,
+  `fetch_headers` (with a security-header report), `trace_redirects` (walks the
+  redirect chain with loop detection).
+- **DNS** — `resolve(host, want_reverse=...)` for forward (A/AAAA + canonical
+  name) and reverse (PTR) lookups via `socket`.
+- **OpenAPI/Swagger** — `load_document` (fetch a URL or read a file),
+  `parse_document`, `summarize_spec` (bounded overview: info, servers,
+  operations) and `describe_operation` (one operation's params, request body and
+  responses, with `$ref`s resolved to bounded schema summaries). Understands
+  OpenAPI 3.x and Swagger 2.0. JSON parses with the stdlib; YAML needs the
+  optional `yaml` extra (`pip install runspec-webops-core[yaml]`). `fetch_body`
+  is the redirect-following, size-capped GET behind it.

runspec_webops_core-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,41 @@
+# runspec-webops-core
+
+Pure-Python HTTPS/TLS certificate + web-endpoint helpers — the importable logic
+core behind the cross-platform web runnables in
+[`runspec-linux`](../runspec-linux) and [`runspec-windows`](../runspec-windows).
+
+Stdlib only (`ssl` / `socket` / `http.client`) — **no `runspec` dependency, 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).
+
+```python
+from runspec_webops_core import connect_peer, leaf_report, probe, resolve
+
+peer = connect_peer("example.com", 443, 10)
+print(leaf_report(peer, warn_days=30))        # days-to-expiry, issuer, SANs, trust
+print(probe("https://example.com", 10))       # status, timing, redirect target
+print(resolve("example.com", want_reverse=True))
+```
+
+| Function | What it does |
+|---|---|
+| `connect_peer` / `leaf_report` / `chain_report` | TLS certificate inspection — expiry, issuer, SANs, fingerprint, full chain, trust result |
+| `probe` / `classify` | Single HTTP(S) request — status, response time, redirect target |
+| `fetch_headers` | Response headers + a security-header report (HSTS, CSP, …) |
+| `trace_redirects` | Walk the redirect chain, hop by hop, with loop detection |
+| `resolve` | Forward (A/AAAA) and reverse (PTR) DNS lookups |
+| `load_document` / `summarize_spec` / `describe_operation` | Read an OpenAPI/Swagger spec (URL or file) and condense its shape — operations, params, request/response schemas — to bounded JSON |
+
+OpenAPI/Swagger specs in JSON parse with the stdlib; YAML needs the optional
+`yaml` extra (`pip install runspec-webops-core[yaml]`).
+
+Each function returns plain data and *raises* on failure (`ConnectError`,
+`ResolveError` — both subclasses of `WebopsCoreError`).
+
+## Corporate wrapping
+
+Depend on `runspec-webops-core` alone, import the helpers, and ship your own
+private package with its own `runspec.toml` that bakes in corporate defaults
+(proxies, allowed hosts, redaction) as plain params — only your wrapped
+runnables surface in the venv, the generic published code stays clean.

runspec_webops_core-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-webops-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python HTTPS/TLS certificate + web-endpoint helpers — the importable core behind the runspec web runnables (no runspec dependency, no runnables)"
+dependencies = []
+
+[project.optional-dependencies]
+# Optional: parse YAML OpenAPI/Swagger specs. JSON specs need no extra.
+yaml = [
+    "pyyaml>=6.0",
+]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+    "pyyaml>=6.0",
+    "types-pyyaml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_webops_core-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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),
+    }