runspec-webops-core 0.2.0__tar.gz → 0.3.1__tar.gz

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/.gitignore

@@ -59,3 +59,6 @@ chainlit-docs/
 
 # Stray committed test venv (removed from tracking)
 .venv-test/
+
+# Private gitleaks rules (see .gitleaks.toml)
+.gitleaks.local.toml

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # runspec-webops-core Changelog
 
+## [0.3.1] — 2026-11-05
+
+### Fixed
+
+- The PyPI page shows the README (`pyproject.toml` didn't declare it).
+
+## [0.3.0] — 2026-09-01
+
+### Added — custom CA bundle for TLS verification
+
+- Every network helper gained a `ca_bundle` parameter (a PEM path): `probe`,
+  `fetch_headers`, `trace_redirects`, `fetch_body`, `load_document`, and
+  `connect_peer`. It verifies TLS against a **private/internal CA or a
+  TLS-intercepting proxy** — the common companion to proxy support, since a
+  corporate proxy that inspects TLS presents its own CA. `insecure` still turns
+  verification off entirely and overrides `ca_bundle`.
+- New `client_ssl_context(insecure=False, ca_bundle=None)` centralises client
+  SSL-context construction (used by the HTTP and TLS-trust paths); a bad bundle
+  path raises a clear `ConnectError`. Exported from the package.
+- For `connect_peer`, `ca_bundle` affects only the trust verdict — the
+  inspection connection stays unverified, so the chain is still reported for an
+  untrusted endpoint.
+
 ## [0.2.0] — 2026-08-26
 
 ### Added — proxy discovery + CONNECT tunnelling

runspec_webops_core-0.3.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: runspec-webops-core
+Version: 0.3.1
+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==0.15.20; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# runspec-webops-core
+
+Pure-Python HTTPS/TLS certificate + web-endpoint helpers — the importable logic
+core behind the cross-platform web runnables in
+[`runspec-linux`](https://pypi.org/project/runspec-linux/) and [`runspec-windows`](https://pypi.org/project/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.2.0 → runspec_webops_core-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 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).
+[`runspec-linux`](https://pypi.org/project/runspec-linux/) and [`runspec-windows`](https://pypi.org/project/runspec-windows/).
 
 Stdlib only (`ssl` / `socket` / `http.client`) — **no `runspec` dependency, no
 `runspec.toml`, and no entry points**, so installing it exposes the helper

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/pyproject.toml

@@ -4,9 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-webops-core"
-version = "0.2.0"
+version = "0.3.1"
 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)"
+readme = "README.md"
 dependencies = []
 
 [project.optional-dependencies]

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/runspec_webops_core/__init__.py

@@ -33,6 +33,7 @@ from runspec_webops_core.tls import (
     TlsPeer,
     cert_status,
     chain_report,
+    client_ssl_context,
     connect_peer,
     days_until,
     leaf_report,
@@ -52,6 +53,7 @@ __all__ = [
     "chain_report",
     "days_until",
     "cert_status",
+    "client_ssl_context",
     # http
     "probe",
     "classify",

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/runspec_webops_core/http.py

@@ -16,6 +16,7 @@ from urllib.parse import urljoin, urlsplit
 
 from runspec_webops_core.errors import ConnectError
 from runspec_webops_core.proxy import http_connection, resolve_proxy
+from runspec_webops_core.tls import client_ssl_context
 
 _USER_AGENT = "runspec-webops"
 
@@ -43,13 +44,14 @@ def classify(status: int) -> str:
     return "unknown"
 
 
-def _request(url: str, timeout: float, method: str, insecure: bool, proxy: str | None = None) -> tuple[int, str, list[tuple[str, str]], float]:
+def _request(url: str, timeout: float, method: str, insecure: bool, proxy: str | None = None, ca_bundle: str | None = None) -> tuple[int, str, list[tuple[str, str]], float]:
     """Issue one request and return ``(status, reason, headers, elapsed_ms)``.
 
     ``proxy`` overrides proxy resolution for this request (``"direct"`` forces no
     proxy); when ``None`` the proxy is auto-discovered from the environment and,
-    on Windows, the system configuration. Raises :class:`ConnectError` on any
-    transport-level failure.
+    on Windows, the system configuration. ``ca_bundle`` is a PEM path of extra CA
+    certs to verify against (private CA / TLS-intercepting proxy); ``insecure``
+    overrides it. Raises :class:`ConnectError` on any transport-level failure.
     """
     parts = urlsplit(url)
     if parts.scheme not in ("http", "https"):
@@ -63,12 +65,7 @@ def _request(url: str, timeout: float, method: str, insecure: bool, proxy: str |
     if parts.query:
         path = f"{path}?{parts.query}"
 
-    ctx = None
-    if is_https:
-        ctx = ssl.create_default_context()
-        if insecure:
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE
+    ctx = client_ssl_context(insecure, ca_bundle) if is_https else None
 
     resolved = resolve_proxy(url, proxy)
     conn, prefix, extra_headers = http_connection(parts.scheme, parts.hostname, port, timeout, ctx, resolved)
@@ -87,14 +84,16 @@ def _request(url: str, timeout: float, method: str, insecure: bool, proxy: str |
         conn.close()
 
 
-def fetch_body(url: str, timeout: float = 15.0, insecure: bool = False, max_bytes: int = 10_000_000, max_redirects: int = 5, proxy: str | None = None) -> tuple[int, str]:
+def fetch_body(url: str, timeout: float = 15.0, insecure: bool = False, max_bytes: int = 10_000_000, max_redirects: int = 5, proxy: str | None = None, ca_bundle: str | None = None) -> 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. ``proxy`` overrides proxy resolution
     (``"direct"`` forces none; ``None`` auto-discovers) and is re-evaluated per
-    redirect hop, so a cross-host bypass is honoured. Raises :class:`ConnectError`
-    on a transport failure or when the body exceeds ``max_bytes``.
+    redirect hop, so a cross-host bypass is honoured. ``ca_bundle`` is a PEM path
+    of extra CA certs to verify against (private CA / TLS proxy); ``insecure``
+    overrides it. Raises :class:`ConnectError` on a transport failure or when the
+    body exceeds ``max_bytes``.
     """
     current = url
     seen: set[str] = set()
@@ -114,12 +113,7 @@ def fetch_body(url: str, timeout: float = 15.0, insecure: bool = False, max_byte
         if parts.query:
             path = f"{path}?{parts.query}"
 
-        ctx = None
-        if is_https:
-            ctx = ssl.create_default_context()
-            if insecure:
-                ctx.check_hostname = False
-                ctx.verify_mode = ssl.CERT_NONE
+        ctx = client_ssl_context(insecure, ca_bundle) if is_https else None
 
         resolved = resolve_proxy(current, proxy)
         conn, prefix, extra_headers = http_connection(parts.scheme, parts.hostname, port, timeout, ctx, resolved)
@@ -157,9 +151,9 @@ def _header(headers: list[tuple[str, str]], name: str) -> str | None:
     return None
 
 
-def probe(url: str, timeout: float = 10.0, method: str = "GET", insecure: bool = False, proxy: str | None = None) -> dict:
+def probe(url: str, timeout: float = 10.0, method: str = "GET", insecure: bool = False, proxy: str | None = None, ca_bundle: str | None = None) -> dict:
     """Single-request probe: status, timing, ``server`` / ``location`` headers."""
-    status, reason, headers, elapsed = _request(url, timeout, method, insecure, proxy)
+    status, reason, headers, elapsed = _request(url, timeout, method, insecure, proxy, ca_bundle)
     return {
         "url": url,
         "status": status,
@@ -171,9 +165,9 @@ def probe(url: str, timeout: float = 10.0, method: str = "GET", insecure: bool =
     }
 
 
-def fetch_headers(url: str, timeout: float = 10.0, method: str = "HEAD", insecure: bool = False, proxy: str | None = None) -> dict:
+def fetch_headers(url: str, timeout: float = 10.0, method: str = "HEAD", insecure: bool = False, proxy: str | None = None, ca_bundle: str | None = None) -> dict:
     """Fetch response headers and report on the security headers (present/missing)."""
-    status, reason, headers, elapsed = _request(url, timeout, method, insecure, proxy)
+    status, reason, headers, elapsed = _request(url, timeout, method, insecure, proxy, ca_bundle)
     header_map = {key.lower(): value for key, value in headers}
     security: dict[str, str | None] = {}
     missing: list[str] = []
@@ -194,7 +188,7 @@ def fetch_headers(url: str, timeout: float = 10.0, method: str = "HEAD", insecur
     }
 
 
-def trace_redirects(url: str, timeout: float = 10.0, max_hops: int = 10, insecure: bool = False, proxy: str | None = None) -> dict:
+def trace_redirects(url: str, timeout: float = 10.0, max_hops: int = 10, insecure: bool = False, proxy: str | None = None, ca_bundle: str | None = None) -> dict:
     """Walk the redirect chain, recording each hop until a non-3xx or ``max_hops``."""
     hops: list[dict] = []
     seen: set[str] = set()
@@ -205,7 +199,7 @@ def trace_redirects(url: str, timeout: float = 10.0, max_hops: int = 10, insecur
             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, proxy)
+        status, reason, headers, elapsed = _request(current, timeout, "GET", insecure, proxy, ca_bundle)
         location = _header(headers, "location")
         hops.append(
             {

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/runspec_webops_core/openapi.py

@@ -39,14 +39,16 @@ class SpecError(WebopsCoreError):
 # ── loading ───────────────────────────────────────────────────────────────────
 
 
-def load_document(source: str, timeout: float = 15.0, insecure: bool = False, proxy: str | None = None) -> dict:
+def load_document(source: str, timeout: float = 15.0, insecure: bool = False, proxy: str | None = None, ca_bundle: str | None = None) -> dict:
     """Fetch (URL) or read (file path) a spec and parse it into a dict.
 
     ``proxy`` is forwarded to the fetch for URL sources (``"direct"`` forces no
-    proxy; ``None`` auto-discovers); it is ignored for local file paths.
+    proxy; ``None`` auto-discovers); ``ca_bundle`` (a PEM path) is forwarded too
+    for verifying against a private CA / TLS proxy. Both are ignored for local
+    file paths.
     """
     if source.startswith(("http://", "https://")):
-        status, body = fetch_body(source, timeout=timeout, insecure=insecure, proxy=proxy)
+        status, body = fetch_body(source, timeout=timeout, insecure=insecure, proxy=proxy, ca_bundle=ca_bundle)
         if status >= 400:
             raise SpecError(f"fetching {source} returned HTTP {status}")
     else:

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/runspec_webops_core/tls.py

@@ -180,6 +180,24 @@ def chain_report(peer: TlsPeer, now: float | None = None) -> list[dict]:
 # ── network I/O ───────────────────────────────────────────────────────────────
 
 
+def client_ssl_context(insecure: bool = False, ca_bundle: str | None = None) -> ssl.SSLContext:
+    """Build a verifying client SSL context, optionally trusting a custom CA bundle.
+
+    ``ca_bundle`` is a path to a PEM file of extra CA certificate(s) to verify
+    against — for a private/internal CA or a TLS-intercepting proxy. ``insecure``
+    turns verification off entirely (``CERT_NONE``), which overrides ``ca_bundle``.
+    Raises :class:`ConnectError` when the bundle path can't be loaded.
+    """
+    try:
+        ctx = ssl.create_default_context(cafile=ca_bundle) if ca_bundle else ssl.create_default_context()
+    except OSError as e:
+        raise ConnectError(f"could not load CA bundle {ca_bundle!r}: {e}") from e
+    if insecure:
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
 def _peer_chain(ssock: ssl.SSLSocket) -> list[CertInfo]:
     """Return the server-presented certificate chain (leaf first).
 
@@ -225,9 +243,12 @@ def _decode_der(der: bytes) -> dict:
         Path(path).unlink(missing_ok=True)
 
 
-def _verify_trust(host: str, port: int, servername: str, timeout: float, proxy: str | None = None) -> tuple[bool, str | None]:
-    """Second connection with full verification — captures the trust verdict."""
-    ctx = ssl.create_default_context()
+def _verify_trust(host: str, port: int, servername: str, timeout: float, proxy: str | None = None, ca_bundle: str | None = None) -> tuple[bool, str | None]:
+    """Second connection with full verification — captures the trust verdict.
+
+    ``ca_bundle`` adds a custom CA to the trust store (private CA / TLS proxy).
+    """
+    ctx = client_ssl_context(ca_bundle=ca_bundle)
     try:
         with open_socket(host, port, timeout, proxy) as sock, ctx.wrap_socket(sock, server_hostname=servername):
             return True, None
@@ -241,13 +262,15 @@ def _verify_trust(host: str, port: int, servername: str, timeout: float, proxy:
         return False, str(e)
 
 
-def connect_peer(host: str, port: int = 443, timeout: float = 10.0, servername: str | None = None, proxy: str | None = None) -> TlsPeer:
+def connect_peer(host: str, port: int = 443, timeout: float = 10.0, servername: str | None = None, proxy: str | None = None, ca_bundle: str | None = None) -> TlsPeer:
     """Open a TLS connection and capture the cert chain, protocol, cipher, trust.
 
     ``proxy`` overrides proxy resolution (``"direct"`` forces none; ``None``
     auto-discovers from the environment and, on Windows, the system config). When
     a proxy applies the connection is CONNECT-tunnelled, so the certificate
-    inspected is the real host's, not the proxy's.
+    inspected is the real host's, not the proxy's. ``ca_bundle`` is a PEM path
+    used only for the trust verdict — the inspection connection is unverified
+    regardless, so the chain is still reported for an untrusted endpoint.
 
     Raises :class:`ConnectError` only when the endpoint is unreachable — an
     untrusted / expired certificate is reported, not raised.
@@ -265,7 +288,7 @@ def connect_peer(host: str, port: int = 443, timeout: float = 10.0, servername:
     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, resolved)
+    authorized, auth_error = _verify_trust(host, port, sni, timeout, resolved, ca_bundle)
     return TlsPeer(
         chain=chain,
         protocol=protocol,

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/tests/test_http.py

@@ -78,6 +78,12 @@ def test_probe_bad_scheme_raises() -> None:
         probe("ftp://example.com", timeout=2)
 
 
+def test_probe_bad_ca_bundle_raises() -> None:
+    # A missing CA bundle fails at context build, before any network I/O.
+    with pytest.raises(ConnectError, match="CA bundle"):
+        probe("https://example.com", timeout=2, ca_bundle="/no/such/ca.pem")
+
+
 def test_fetch_headers_flags_missing_security(server: str) -> None:
     res = fetch_headers(f"{server}/ok", timeout=5)
     assert res["security"]["strict_transport_security"] == "max-age=63072000"

{runspec_webops_core-0.2.0 → runspec_webops_core-0.3.1}/tests/test_tls.py

@@ -1,10 +1,12 @@
 """Pure TLS reporting logic — no socket required."""
 
+import ssl
 from datetime import datetime, timezone
+from pathlib import Path
 
 import pytest
 
-from runspec_webops_core import cert_status, chain_report, days_until, leaf_report
+from runspec_webops_core import cert_status, chain_report, client_ssl_context, days_until, leaf_report
 from runspec_webops_core.errors import ConnectError
 from runspec_webops_core.tls import (
     EXPIRED,
@@ -48,6 +50,34 @@ def test_issuer_label_prefers_cn_then_org() -> None:
     assert _issuer_label(((("organizationName", "Acme"),),)) == "Acme"
 
 
+def test_client_ssl_context_default_verifies() -> None:
+    ctx = client_ssl_context()
+    assert ctx.verify_mode == ssl.CERT_REQUIRED
+    assert ctx.check_hostname is True
+
+
+def test_client_ssl_context_insecure_disables_verification() -> None:
+    ctx = client_ssl_context(insecure=True)
+    assert ctx.verify_mode == ssl.CERT_NONE
+    assert ctx.check_hostname is False
+
+
+def test_client_ssl_context_loads_ca_bundle(tmp_path) -> None:
+    # A valid PEM (a copy of the system default CAs) loads without error.
+    system_cafile = ssl.get_default_verify_paths().cafile
+    if not system_cafile or not Path(system_cafile).is_file():
+        pytest.skip("no system CA bundle to copy")
+    bundle = tmp_path / "ca.pem"
+    bundle.write_text(Path(system_cafile).read_text())
+    ctx = client_ssl_context(ca_bundle=str(bundle))
+    assert ctx.verify_mode == ssl.CERT_REQUIRED
+
+
+def test_client_ssl_context_bad_ca_bundle_raises() -> None:
+    with pytest.raises(ConnectError, match="CA bundle"):
+        client_ssl_context(ca_bundle="/no/such/ca-bundle.pem")
+
+
 def _ssl_info(cn: str, issuer_cn: str, not_after: str) -> dict:
     return {
         "subject": ((("commonName", cn),),),

runspec_webops_core-0.2.0/PKG-INFO

@@ -1,13 +0,0 @@
-Metadata-Version: 2.5
-Name: runspec-webops-core
-Version: 0.2.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==0.15.20; extra == 'dev'
-Requires-Dist: types-pyyaml; extra == 'dev'
-Provides-Extra: yaml
-Requires-Dist: pyyaml>=6.0; extra == 'yaml'