opskit 0.1.0__py3-none-any.whl

opskit/net/tcp.py

@@ -0,0 +1,164 @@
+"""Reusable TCP resolve/connect primitive (the seam the future net category builds on).
+
+Pure stdlib sockets: :func:`resolve` orders candidates via ``getaddrinfo`` (dual-stack order is
+the platform's), :func:`connect` walks them with timeout/retries and normalizes raw ``OSError``
+into the :mod:`opskit.net.errors` hierarchy. Nothing here prints or exits (Art. VII).
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import socket
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from opskit.net.errors import ConnectRefused, ConnectTimeout, ResolutionError
+
+
+@dataclass(frozen=True)
+class AddressCandidate:
+    """One resolved address a connection may be attempted against."""
+
+    address: str
+    family: str  # "ipv4" | "ipv6"
+    sockaddr: tuple[Any, ...]
+    af: int  # socket.AF_* constant
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this candidate."""
+        return {"address": self.address, "family": self.family}
+
+
+@dataclass(frozen=True)
+class TcpConnection:
+    """Facts about an established TCP connection (returned alongside the socket)."""
+
+    address: str
+    family: str  # "ipv4" | "ipv6"
+    port: int
+    connect_ms: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this connection."""
+        return {
+            "address": self.address,
+            "family": self.family,
+            "port": self.port,
+            "connect_ms": round(self.connect_ms, 3),
+        }
+
+
+def _family_name(af: int) -> str:
+    return "ipv6" if af == socket.AF_INET6 else "ipv4"
+
+
+def resolve(host: str, port: int, *, timeout: float = 5.0) -> list[AddressCandidate]:
+    """Resolve ``host`` to ordered address candidates (platform dual-stack order).
+
+    Args:
+        host: Hostname or IP literal.
+        port: Target port (carried into the socket addresses).
+        timeout: Wall-clock budget for the lookup. ``socket.getaddrinfo`` has no per-call
+            timeout, so it runs off-thread and is abandoned after ``timeout`` seconds.
+
+    Returns:
+        Candidates in the order the platform recommends trying them.
+
+    Raises:
+        ResolutionError: If the name does not resolve or resolution exceeds ``timeout``.
+    """
+    executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+    future = executor.submit(socket.getaddrinfo, host, port, type=socket.SOCK_STREAM)
+    try:
+        infos = future.result(timeout=timeout)
+    except concurrent.futures.TimeoutError as exc:
+        raise ResolutionError(
+            f"resolving {host} timed out after {timeout}s",
+            hint="the resolver may be slow or unreachable; diagnose with: opskit dns lookup "
+            + host,
+        ) from exc
+    except OSError as exc:
+        raise ResolutionError(
+            f"cannot resolve {host}: {exc}",
+            hint="check the name for typos, or diagnose with: opskit dns lookup "
+            + host,
+        ) from exc
+    finally:
+        # A lookup that timed out keeps running in the worker; don't block on it (the OS
+        # resolver abandons it per resolv.conf), just release the executor.
+        executor.shutdown(wait=False)
+    candidates: list[AddressCandidate] = []
+    for af, _, _, _, sockaddr in infos:
+        candidates.append(
+            AddressCandidate(
+                address=str(sockaddr[0]),
+                family=_family_name(af),
+                sockaddr=tuple(sockaddr),
+                af=af,
+            )
+        )
+    if not candidates:
+        raise ResolutionError(f"cannot resolve {host}: no addresses returned")
+    return candidates
+
+
+def connect(
+    host: str,
+    port: int,
+    *,
+    timeout: float = 5.0,
+    retries: int = 2,
+) -> tuple[socket.socket, TcpConnection]:
+    """Open a TCP connection to ``host:port``; the caller owns (and must close) the socket.
+
+    Candidates are tried in :func:`resolve` order; timeouts are retried up to ``retries``
+    times across the candidate list, while a refusal on every candidate fails immediately.
+
+    Returns:
+        The connected socket (timeout still set) and a :class:`TcpConnection` report.
+
+    Raises:
+        ResolutionError: If the name does not resolve.
+        ConnectRefused: If every candidate refused / was unreachable.
+        ConnectTimeout: If no candidate answered before the timeout (after retries).
+    """
+    candidates = resolve(host, port, timeout=timeout)
+    start = time.perf_counter()
+    saw_timeout = False
+    refused_exc: BaseException | None = None
+    timeout_exc: BaseException | None = None
+    for _ in range(retries + 1):
+        for candidate in candidates:
+            sock = socket.socket(candidate.af, socket.SOCK_STREAM)
+            sock.settimeout(timeout)
+            try:
+                sock.connect(candidate.sockaddr)
+            except socket.timeout as exc:
+                sock.close()
+                saw_timeout = True
+                timeout_exc = exc
+            except OSError as exc:
+                sock.close()
+                refused_exc = exc
+            else:
+                connect_ms = (time.perf_counter() - start) * 1000.0
+                return sock, TcpConnection(
+                    address=candidate.address,
+                    family=candidate.family,
+                    port=port,
+                    connect_ms=connect_ms,
+                )
+        # A refusal is definitive (host reachable, port closed) — don't retry or wait for
+        # a slow sibling address; only pure-timeout runs are worth retrying.
+        if refused_exc is not None or not saw_timeout:
+            break
+    if refused_exc is not None:
+        raise ConnectRefused(
+            f"cannot connect to {host}:{port}: {refused_exc}",
+            hint="check that the service is listening on this port",
+        ) from refused_exc
+    raise ConnectTimeout(
+        f"no response from {host}:{port} within {timeout}s",
+        hint="the port may be filtered; verify reachability and firewall rules",
+    ) from timeout_exc

opskit/tls/README.md

@@ -0,0 +1,150 @@
+# `opskit tls` — TLS verification
+
+Read-only TLS/certificate verification that behaves **identically on Windows, macOS, and
+Linux** — a single replacement for `openssl s_client` incantations. Available both as a CLI
+command and as an importable Python API.
+
+> Part of [**opskit**](../../../README.md). See the root README for install and project-wide docs.
+
+---
+
+## Contents
+
+- [Quick start](#quick-start)
+- [`opskit tls check`](#opskit-tls-check)
+- [Layered outcomes & exit codes](#layered-outcomes--exit-codes)
+- [Trust & name validation](#trust--name-validation)
+- [Expiry warnings & watch](#expiry-warnings--watch)
+- [Bulk checks](#bulk-checks)
+- [Output](#output)
+- [Use as a Python library](#use-as-a-python-library)
+
+---
+
+## Quick start
+
+```bash
+opskit tls check example.com                     # full verdict, port 443
+opskit tls check example.com:8443                # non-standard port (or -p 8443)
+opskit tls check 192.0.2.10 --sni internal.corp  # IP endpoint, verify a vhost identity
+opskit tls check ldap.corp.example:636 --ca-file corp-root.pem   # private PKI
+opskit tls check example.com --json              # machine-readable envelope
+```
+
+The report always shows the verdict, the leaf certificate (subject, issuer, SANs, validity,
+days to expiry, serial, signature algorithm, key), the presented chain, the negotiated
+protocol/cipher, and every failed condition with an actionable hint — **certificate details
+are shown even when validation fails**, so you can inspect the bad certificate instead of
+just being told it's bad.
+
+## `opskit tls check`
+
+```bash
+opskit tls check [TARGET] [OPTIONS]
+```
+
+`TARGET` accepts `host`, `host:port`, IPv4/IPv6 literals, or `[ipv6]:port`.
+
+| Option | Description | Default |
+|---|---|---|
+| `-p, --port` | Port to check (must agree with a `host:port` shorthand) | `443` |
+| `--sni` | Server name to send & verify (see below) | target hostname |
+| `--ca-file` | PEM bundle replacing the platform trust store (private PKI) | platform store |
+| `--warn-days` | Expiring-soon threshold in days (`0` disables) | `30` |
+| `--timeout` | Per-attempt timeout (connect and handshake each), seconds | `5.0` |
+| `--retries` | Retries on timeout | `2` |
+| `-i, --input-file` | File of targets, one `host[:port]` per line (`#` comments allowed) | — |
+| `--watch` | Re-run every interval (e.g. `30s`, `2m`) until Ctrl-C | off |
+| `--json` / `--jsonl` | Versioned JSON envelope / NDJSON per target | off |
+| `--no-color` | Disable colored output (`NO_COLOR` honored too) | off |
+
+## Layered outcomes & exit codes
+
+The check walks resolve → connect → handshake → validate and reports **which layer broke**:
+
+| Code | Meaning | Layer |
+|---|---|---|
+| `0` | TLS healthy | |
+| `1` | generic error | |
+| `2` | usage error (bad target/controls; before any network) | pre-flight |
+| `3` | name resolution failure | resolve |
+| `6` | timeout (connect or handshake, after retries) | connect/handshake |
+| `7` | PARTIAL (batch with mixed outcomes) | aggregate |
+| `8` | connection failed (refused / unreachable) | connect |
+| `9` | handshake failed (incl. non-TLS service; STARTTLS is out of scope) | handshake |
+| `10` | certificate invalid (expired, not-yet-valid, name mismatch, self-signed, untrusted/incomplete chain) | validate |
+| `11` | certificate valid but expiring soon (within `--warn-days`) | validate |
+
+Distinct certificate conditions are reported separately: **expired** vs **not yet valid**,
+**self-signed** vs **untrusted chain** vs **incomplete chain** (server forgot the
+intermediate), **name mismatch** (shows requested vs covered names), and **no SANs** (legacy
+CN-only certificates).
+
+**Protocol floor**: opskit is secure-by-default and requires **TLS 1.2 or newer**. A server
+that offers only SSLv3 / TLS 1.0 / 1.1 fails the handshake (exit 9) with a hint, rather than
+opskit negotiating down to a weak protocol.
+
+## Trust & name validation
+
+- Chain validation uses the **platform trust store** by default (Windows certificate stores,
+  macOS/Linux OpenSSL paths); `--ca-file` replaces it entirely for private PKI.
+- Name matching follows RFC 6125: exact DNS-SAN match, a wildcard covers exactly one
+  left-most label (`*.example.com` matches `a.example.com`, never `example.com` or
+  `a.b.example.com`), IP targets match IP SANs, and there is no CN fallback.
+- **SNI**: the target hostname is sent by default and omitted for IP targets. With `--sni`,
+  the given name is both sent *and* used for name validation — so
+  `opskit tls check 192.0.2.10 --sni internal.corp` verifies the `internal.corp` identity on
+  that IP (split-horizon / pre-DNS setups).
+- Revocation (OCSP/CRL) is not checked: opskit connects **only** to the endpoint you name.
+
+## Expiry warnings & watch
+
+```bash
+opskit tls check example.com --warn-days 14      # exit 11 if < 14 days remain
+opskit tls check example.com --watch 30s         # flag outcome/certificate changes
+```
+
+`--watch` flags a change when the outcome class, the leaf fingerprint (rotation!), the
+expiry date, or the negotiated protocol changes — timing jitter is ignored.
+
+## Bulk checks
+
+```bash
+opskit tls check -i endpoints.txt --jsonl | jq .
+```
+
+Every target is processed (one failure never aborts the batch); failed targets appear in the
+JSON output with their error; the exit code is `0` only if all pass, the class code if all
+failures share one class, else `7`.
+
+## Output
+
+`--json` emits the versioned envelope (`schema_version`, `command: "tls.check"`, `query`,
+`result`, `error`, `elapsed_ms`); `--jsonl` emits one envelope per line. The `result` object
+carries the outcome, connection (address/family/timing), `tls_version`, `cipher`, `leaf`,
+`chain`, and `findings`.
+
+## Use as a Python library
+
+```python
+from opskit.tls import check, CertificateInvalid
+
+result = check("example.com:443", warn_days=14)
+print(result.outcome.value, result.tls_version, result.cipher)
+print(result.leaf.subject, result.leaf.days_until_expiry)
+for cert in result.chain:
+    print(" ", cert.subject, "->", cert.issuer)
+for finding in result.findings:
+    print("!", finding.code.value, finding.message)
+
+try:
+    check("expired.badssl.com", raise_on_invalid=True)
+except CertificateInvalid as exc:
+    print(exc.message, "—", exc.hint)
+```
+
+Completed handshakes **return** a result (even for bad certificates — details stay
+inspectable); failures that preclude a report (resolve/connect/handshake) **raise** typed
+errors from `opskit.net` / `opskit.tls`. `raise_on_invalid=True` opts into exceptions for
+certificate conditions too. The TCP primitive is importable from `opskit.net`
+(`resolve`/`connect`) for building your own network tooling.

opskit/tls/__init__.py

@@ -0,0 +1,39 @@
+"""TLS verification diagnostics — importable API and CLI sub-app.
+
+Public surface (SemVer-governed): :func:`check`, the typed models, and the TLS exception
+hierarchy. Failures raise; nothing here prints or exits the process.
+"""
+
+from __future__ import annotations
+
+from opskit.tls.api import check
+from opskit.tls.errors import (
+    CertificateExpiring,
+    CertificateInvalid,
+    HandshakeError,
+    TlsError,
+)
+from opskit.tls.models import (
+    CertificateInfo,
+    FindingCode,
+    TlsCheckResult,
+    TlsOutcome,
+    TlsTarget,
+    ValidationFinding,
+    parse_target,
+)
+
+__all__ = [
+    "CertificateExpiring",
+    "CertificateInfo",
+    "CertificateInvalid",
+    "FindingCode",
+    "HandshakeError",
+    "TlsCheckResult",
+    "TlsError",
+    "TlsOutcome",
+    "TlsTarget",
+    "ValidationFinding",
+    "check",
+    "parse_target",
+]

opskit/tls/api.py

@@ -0,0 +1,151 @@
+"""Public TLS verification API — the CLI is a thin client over this module.
+
+:func:`check` orchestrates the layers (resolve → connect → handshake → validate). Failures
+that preclude a report **raise** (usage, resolve, connect, handshake); completed handshakes
+**return** a :class:`TlsCheckResult` whose findings carry certificate conditions, so a bad
+certificate's details stay inspectable (FR-006). Nothing here prints or calls ``sys.exit``.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from opskit.core.errors import UsageError
+from opskit.net import connect as net_connect
+from opskit.tls.errors import CertificateExpiring, CertificateInvalid
+from opskit.tls.handshake import perform_handshake
+from opskit.tls.inspect import build_findings, match_hostname, parse_certificate
+from opskit.tls.models import (
+    FindingCode,
+    TlsCheckResult,
+    TlsOutcome,
+    parse_target,
+)
+
+_INVALID_FINDINGS = frozenset(
+    {
+        FindingCode.EXPIRED,
+        FindingCode.NOT_YET_VALID,
+        FindingCode.NAME_MISMATCH,
+        FindingCode.SELF_SIGNED,
+        FindingCode.UNTRUSTED_CHAIN,
+        FindingCode.INCOMPLETE_CHAIN,
+        FindingCode.NO_SANS,
+    }
+)
+
+
+def _validate_controls(timeout: float, retries: int, warn_days: int) -> None:
+    if timeout <= 0:
+        raise UsageError("timeout must be positive")
+    if retries < 0:
+        raise UsageError("retries must be >= 0")
+    if warn_days < 0:
+        raise UsageError("warn-days must be >= 0")
+
+
+def check(
+    target: str,
+    *,
+    port: int | None = None,
+    server_name: str | None = None,
+    ca_file: str | Path | None = None,
+    warn_days: int = 30,
+    timeout: float = 5.0,
+    retries: int = 2,
+    raise_on_invalid: bool = False,
+) -> TlsCheckResult:
+    """Verify the TLS health of ``target`` (``host``, ``host:port``, IP, ``[v6]:port``).
+
+    Args:
+        target: Endpoint to check; the port defaults to 443.
+        port: Explicit port (must agree with any ``host:port`` shorthand).
+        server_name: SNI override; defaults to the hostname, omitted for IP targets.
+        ca_file: PEM bundle replacing the platform trust store (private PKI).
+        warn_days: Expiring-soon threshold in days (0 disables the warning class).
+        timeout: Per-attempt timeout for connect and handshake, seconds.
+        retries: Retries on timeout.
+        raise_on_invalid: Raise :class:`CertificateInvalid`/:class:`CertificateExpiring`
+            instead of returning a result whose outcome carries those conditions.
+
+    Returns:
+        A :class:`TlsCheckResult` with the layered outcome, negotiated protocol/cipher,
+        parsed leaf + chain, and validation findings.
+
+    Raises:
+        UsageError: Invalid target or controls (before any network I/O).
+        ResolutionError: The host does not resolve.
+        ConnectRefused: The port refused / was unreachable.
+        ConnectTimeout: Connect or handshake timed out (after retries).
+        HandshakeError: The TLS handshake failed (e.g. non-TLS service).
+        CertificateInvalid: Only with ``raise_on_invalid=True``.
+        CertificateExpiring: Only with ``raise_on_invalid=True``.
+    """
+    parsed = parse_target(target, port=port, server_name=server_name)
+    _validate_controls(timeout, retries, warn_days)
+
+    start = time.perf_counter()
+    sock, connection = net_connect(
+        parsed.host, parsed.port, timeout=timeout, retries=retries
+    )
+    try:
+        outcome = perform_handshake(
+            sock,
+            server_name=parsed.server_name,
+            timeout=timeout,
+            ca_file=ca_file,
+        )
+    finally:
+        sock.close()
+
+    chain = tuple(parse_certificate(cert) for cert in outcome.chain)
+    leaf_raw = outcome.chain[0] if outcome.chain else None
+    leaf = chain[0] if chain else None
+    if leaf is None or leaf_raw is None:
+        # A handshake without a peer certificate is not a usable TLS endpoint.
+        raise CertificateInvalid(
+            "server presented no certificate",
+            hint="the endpoint may require a protocol opskit does not speak",
+        )
+
+    findings = build_findings(
+        parsed,
+        leaf,
+        name_matched=match_hostname(parsed, leaf_raw),
+        verify_errors=outcome.verify_errors,
+        chain_length=len(chain),
+        tls_version=outcome.tls_version,
+        warn_days=warn_days,
+    )
+
+    codes = {finding.code for finding in findings}
+    if codes & _INVALID_FINDINGS:
+        verdict = TlsOutcome.CERT_INVALID
+    elif FindingCode.EXPIRING_SOON in codes:
+        verdict = TlsOutcome.EXPIRING_SOON
+    else:
+        verdict = TlsOutcome.OK
+
+    result = TlsCheckResult(
+        target=parsed,
+        outcome=verdict,
+        connection=connection,
+        tls_version=outcome.tls_version,
+        cipher=outcome.cipher,
+        leaf=leaf,
+        chain=chain,
+        findings=findings,
+        elapsed_ms=(time.perf_counter() - start) * 1000.0,
+    )
+
+    if raise_on_invalid and verdict is TlsOutcome.CERT_INVALID:
+        first = next(f for f in findings if f.code in _INVALID_FINDINGS)
+        raise CertificateInvalid(first.message, hint=first.hint, findings=findings)
+    if raise_on_invalid and verdict is TlsOutcome.EXPIRING_SOON:
+        raise CertificateExpiring(
+            f"certificate expires in {leaf.days_until_expiry} day(s)",
+            hint="schedule renewal",
+            days_remaining=leaf.days_until_expiry,
+        )
+    return result