cleanlib-sdk 0.4.1__py3-none-any.whl

cleanlib_sdk/__init__.py

@@ -0,0 +1,118 @@
+"""CleanLibrary Python SDK — mirrors @cleanstart/cleanlib-sdk v0.4.x.
+
+Cycle-7 v0.4.1:
+- New per-domain HTTP client split (sister-shape with sdk-js v0.4.1)
+  - `HttpRemediationClient` — sparse 7-block /remediation responses
+  - (HttpVerdictClient + HttpEnrichClient land in v0.4.2 ripple)
+- `cleanlib_sdk.reason_codes.ReasonCode` — 15-entry canonical registry (Enum)
+- `cleanlib_sdk.schema` — `VerdictEnvelopeV1` JSON Schema mirror (Python dict literal)
+- `cleanlib_sdk.derive_status.derive_status(envelope)` — algorithm per App
+  dispatch §4 binding contract (substance precedence + freshness override)
+- `cleanlib_sdk.Client` flat-method class → `DeprecationWarning` on __init__
+  (per F5 ratification; scheduled removal v1.0.0)
+
+Schema-locked against `@cleanstart/cleanlib-sdk@0.4.1` tarball sha-1
+`b5f00c160907a6ea1f490f14a9bda6f6de34b8b6`. Cross-SDK contract test verifies
+identical (status, reason_code) on every fixture in
+`cleanlib-contract-fixtures` v1.0.0.
+
+Earlier cycle context:
+- Cycle-5 v0.3.0 added typed `Verdict.attestation`
+- Cycle-6 v0.4.0 added 5-verb cascade + 9 rich-data Optional fields
+"""
+
+from cleanlib_sdk.client import Client
+from cleanlib_sdk.derive_status import StatusResult, derive_status
+from cleanlib_sdk.errors import (
+    AuthenticationError,
+    CleanLibraryError,
+    InsufficientDataError,
+    IntegrityFailureError,
+    PackageNotFoundError,
+    ParseError,
+    PolicyDenyError,
+    RateLimitExceededError,
+    RiskAcceptanceRequiredError,
+    ServerError,
+    TransportError,
+)
+from cleanlib_sdk.http import (
+    DEFAULT_REMEDIATION_BASE_URL,
+    REMEDIATION_CACHE_TTL_SECS,
+    HttpRemediationClient,
+    RemediationBlock,
+    RemediationOrAbsent,
+    RemediationResponse,
+)
+from cleanlib_sdk.reason_codes import ALL_REASON_CODES, ReasonCode
+from cleanlib_sdk.schema import (
+    AVAILABILITY_ENUM,
+    SCHEMA_ID,
+    STATUS_ENUM,
+    VERDICT_ENVELOPE_V1_SCHEMA,
+)
+from cleanlib_sdk.types import (
+    Attestation,
+    AuditWindow,
+    AuditWindowResponse,
+    PackageRef,
+    PackageRisk,
+    PolicyPreviewResponse,
+    PolicyPreviewResult,
+    RecommendedVersion,
+    RiskAcceptResponse,
+    ScanResponse,
+    ScanResult,
+    SignedAttestation,
+    Verdict,
+)
+
+__version__ = "0.4.1"
+
+__all__ = [
+    # v0.4.1 per-domain HTTP clients (primary API)
+    "HttpRemediationClient",
+    "DEFAULT_REMEDIATION_BASE_URL",
+    "REMEDIATION_CACHE_TTL_SECS",
+    "RemediationBlock",
+    "RemediationResponse",
+    "RemediationOrAbsent",
+    # v0.4.1 contract enforcement
+    "ReasonCode",
+    "ALL_REASON_CODES",
+    "VERDICT_ENVELOPE_V1_SCHEMA",
+    "SCHEMA_ID",
+    "STATUS_ENUM",
+    "AVAILABILITY_ENUM",
+    "derive_status",
+    "StatusResult",
+    # cycle-6 v0.4.0 types
+    "Verdict",
+    "Attestation",
+    "SignedAttestation",
+    "RecommendedVersion",
+    "PackageRisk",
+    "PackageRef",
+    "ScanResult",
+    "ScanResponse",
+    "AuditWindow",
+    "AuditWindowResponse",
+    "PolicyPreviewResult",
+    "PolicyPreviewResponse",
+    "RiskAcceptResponse",
+    # Deprecated v0.4.1 (v1.0.0 removal); kept for source-compat with v0.4.0 callers
+    "Client",
+    # Errors
+    "CleanLibraryError",
+    "PolicyDenyError",
+    "IntegrityFailureError",
+    "RateLimitExceededError",
+    "RiskAcceptanceRequiredError",
+    "AuthenticationError",
+    "InsufficientDataError",
+    "PackageNotFoundError",
+    "ServerError",
+    "TransportError",
+    "ParseError",
+    "__version__",
+]

cleanlib_sdk/client.py

@@ -0,0 +1,236 @@
+"""Async Client — DEPRECATED as of v0.4.1; scheduled removal v1.0.0.
+
+The flat-method `Client` class is superseded by the per-domain client split
+in `cleanlib_sdk.http`:
+
+- `HttpRemediationClient` (v0.4.1; sparse 7-block /remediation responses)
+- `HttpVerdictClient` (v0.4.2 ripple; mirror sdk-js)
+- `HttpEnrichClient` (v0.4.2 ripple; mirror sdk-js)
+
+Existing callers continue to work — instantiating `Client` emits a
+`DeprecationWarning` per F5 ratification (sister-shape with sdk-js v0.4.1
+`CleanlibClient` `@deprecated` shim).
+"""
+
+from __future__ import annotations
+
+import warnings
+from types import TracebackType
+from typing import Optional, Type
+from urllib.parse import quote
+
+import httpx
+
+from cleanlib_sdk.transport import (
+    DEFAULT_TIMEOUT_SECS,
+    auth_headers,
+    map_http_error,
+    validate_endpoint,
+)
+from cleanlib_sdk.types import (
+    AuditWindow,
+    AuditWindowResponse,
+    PackageRef,
+    PolicyPreviewResponse,
+    RiskAcceptResponse,
+    ScanResponse,
+    Verdict,
+)
+
+
+class Client:
+    """DEPRECATED — Async HTTP client for the CleanLibrary App customer endpoints.
+
+    .. deprecated:: 0.4.1
+        Use the per-domain clients in :mod:`cleanlib_sdk.http` instead.
+        Scheduled removal in v1.0.0. Per F5 cycle-7 ratification.
+
+    Example (still works; emits ``DeprecationWarning``)::
+
+        import asyncio
+        from cleanlib_sdk import Client
+
+        async def main():
+            async with Client(
+                endpoint="https://cleanapp.clnstrt.dev",
+                api_key="clk_std_test_001",
+            ) as c:
+                v = await c.fetch_verdict("npm", "lodash", "4.17.21")
+                print(v.decision, v.composite_score)
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: Optional[str] = None,
+        api_version: str = "v1",
+        timeout_secs: float = DEFAULT_TIMEOUT_SECS,
+    ) -> None:
+        warnings.warn(
+            "cleanlib_sdk.Client is deprecated as of v0.4.1; use the per-domain "
+            "clients in cleanlib_sdk.http (HttpRemediationClient + HttpVerdictClient "
+            "+ HttpEnrichClient). Scheduled removal v1.0.0.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.base_url = validate_endpoint(endpoint)
+        self.api_key = api_key
+        self.api_version = api_version
+        self._http = httpx.AsyncClient(
+            headers=auth_headers(api_key),
+            timeout=timeout_secs,
+        )
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self._http.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def fetch_verdict(self, ecosystem: str, package: str, version: str) -> Verdict:
+        """GET /v1/customer/verdicts/{ecosystem}/{package}/{version}.
+
+        Returns the parsed Verdict on 2xx. Raises a typed CleanLibraryError
+        subclass on non-2xx per the App Rev 4 §9.2 reason-code dispatch.
+        """
+        path = (
+            f"{self.base_url}/{self.api_version}/customer/verdicts/"
+            f"{quote(ecosystem, safe='')}/"
+            f"{quote(package, safe='')}/"
+            f"{quote(version, safe='')}"
+        )
+        resp = await self._http.get(path)
+        if resp.is_error:
+            raise map_http_error(resp)
+        data = resp.json()
+        # Inject request-context fields the App doesn't echo back
+        # (App's customer-verdict endpoint returns canonical cleanlib_core::
+        # Verdict shape without ecosystem/package/version path-param echoes)
+        data.setdefault("ecosystem", ecosystem)
+        data.setdefault("package", package)
+        data.setdefault("version", version)
+        # Derive decision from verdict_label + severity per cycle-4 §D.7
+        # demo policy mapping
+        if data.get("decision") is None:
+            data["decision"] = _derive_decision(
+                data.get("verdict") or data.get("source"),
+                data.get("severity"),
+            )
+        return Verdict.model_validate(data)
+
+    async def scan(self, packages: list[PackageRef]) -> ScanResponse:
+        """POST /v1/scan — resolve verdicts for a batch of packages (PR #99).
+
+        Partial-success: a per-package failure surfaces as `error` on its
+        result entry rather than raising. Mirrors cleanlib-sdk-js `scan`.
+        """
+        body = {"packages": [p.model_dump(by_alias=True) for p in packages]}
+        resp = await self._http.post(f"{self.base_url}/{self.api_version}/scan", json=body)
+        if resp.is_error:
+            raise map_http_error(resp)
+        return ScanResponse.model_validate(resp.json())
+
+    async def audit(self, window: Optional[AuditWindow] = None) -> AuditWindowResponse:
+        """GET /v1/audit?since=&until= — audit-window query (PR #99).
+
+        `backend_status` is an honest signal: "not_wired" + empty records means
+        the endpoint is reachable but the audit store is not yet attached
+        App-side. Mirrors cleanlib-sdk-js `audit`.
+        """
+        params: dict[str, str] = {}
+        if window is not None:
+            if window.since is not None:
+                params["since"] = window.since
+            if window.until is not None:
+                params["until"] = window.until
+        resp = await self._http.get(
+            f"{self.base_url}/{self.api_version}/audit", params=params or None
+        )
+        if resp.is_error:
+            raise map_http_error(resp)
+        return AuditWindowResponse.model_validate(resp.json())
+
+    async def policy_preview(
+        self, policy_yaml: str, packages: list[PackageRef]
+    ) -> PolicyPreviewResponse:
+        """POST /v1/policy/preview — preview a candidate policy YAML against a
+        batch of packages WITHOUT persisting it (PR #99). Raises ParseError/
+        HttpError-equivalent on 400 when the YAML fails to parse. Mirrors
+        cleanlib-sdk-js `policyPreview`.
+        """
+        body = {
+            "policy_yaml": policy_yaml,
+            "packages": [p.model_dump(by_alias=True) for p in packages],
+        }
+        resp = await self._http.post(
+            f"{self.base_url}/{self.api_version}/policy/preview", json=body
+        )
+        if resp.is_error:
+            raise map_http_error(resp)
+        return PolicyPreviewResponse.model_validate(resp.json())
+
+    async def risk_accept(self, verdict_id: str, justification: str) -> RiskAcceptResponse:
+        """POST /v1/risk-accept — record a risk-acceptance for a verdict (PR #99).
+
+        `persistence` is "ephemeral" until a CDP accept-write lands. Raises on
+        400 when verdict_id or justification is empty. Mirrors cleanlib-sdk-js
+        `riskAccept`.
+        """
+        body = {"verdict_id": verdict_id, "justification": justification}
+        resp = await self._http.post(
+            f"{self.base_url}/{self.api_version}/risk-accept", json=body
+        )
+        if resp.is_error:
+            raise map_http_error(resp)
+        return RiskAcceptResponse.model_validate(resp.json())
+
+    async def fetch_bytes(self, ecosystem: str, package: str, version: str) -> bytes:
+        """GET /v1/fetch/{ecosystem}/{package}/{version} — raw catalog bytes
+        (PR #99). Returns the application/octet-stream body. Does NOT run the
+        policy evaluator or sign an attestation. Mirrors cleanlib-sdk-js
+        `fetchBytes`.
+        """
+        path = (
+            f"{self.base_url}/{self.api_version}/fetch/"
+            f"{quote(ecosystem, safe='')}/"
+            f"{quote(package, safe='')}/"
+            f"{quote(version, safe='')}"
+        )
+        resp = await self._http.get(path)
+        if resp.is_error:
+            raise map_http_error(resp)
+        return resp.content
+
+
+def _derive_decision(verdict_label: Optional[str], severity: Optional[str]) -> str:
+    """Map App canonical Verdict's verdict_label + severity to decision string.
+
+    Mapping rules per cycle-4 §D.7 static demo policy + cycle-5 fixtures:
+    - VECTOR_VERDICT + High/Critical severity → DENY
+    - VECTOR_VERDICT + lower severity → WARN
+    - DM_THRESHOLD_BLOCK → DENY
+    - INSUFFICIENT_DATA → WARN
+    - ALLOWED_NO_FINDINGS → ALLOW
+    - default → ALLOW
+    """
+    label = (verdict_label or "").upper()
+    sev = (severity or "").upper()
+    if label == "VECTOR_VERDICT":
+        return "DENY" if sev in ("HIGH", "CRITICAL") else "WARN"
+    if label == "DM_THRESHOLD_BLOCK":
+        return "DENY"
+    if label == "INSUFFICIENT_DATA":
+        return "WARN"
+    if label == "ALLOWED_NO_FINDINGS":
+        return "ALLOW"
+    return "ALLOW"

cleanlib_sdk/derive_status.py

@@ -0,0 +1,95 @@
+"""DeriveStatus — canonical algorithm per App dispatch §4 binding contract.
+
+Each CleanLibrary SDK (sdk-js, sdk-py, sdk-go, cleanlib-client Rust) implements
+this algorithm independently from the spec; cross-SDK contract test verifies
+byte-identical `(status, reason_code)` across all four implementations on every
+fixture in `cleanlib-contract-fixtures` v1.0.0.
+
+Precedence:
+
+1. **Substance** (signals top-to-bottom; `unavailable` substrate causes fall-through):
+   - `exploitability.exploitation_likelihood == "CRITICAL"` → DENY + VERDICT_EXPLOITATION_CRITICAL
+   - `exploitability.in_kev` AND `availability.kev == "available"` AND `exploit_risk_score >= 70` → DENY + VERDICT_KEV_LISTED
+   - `rich_data.has_obfuscation` → DENY + VERDICT_OBFUSCATED
+   - `remediation.fix` OR `remediation.recommended_version` present → WARN + VERDICT_HAS_REMEDIATION
+   - `rich_data.abandonment_score >= 0.7` → WARN + VERDICT_ABANDONED
+   - `rich_data.recommended_version` present (under rich_data, not remediation) → ALLOW + VERDICT_RECOMMENDED_VERSION_NEWER
+   - default → ALLOW + VERDICT_CLEAN
+
+2. **Freshness override**: when the substance-driving signal's `availability ==
+   "degraded_stale"`, the substance-derived status tier is PRESERVED and the
+   `reason_code` overrides to `VERDICT_DEGRADED_STALE`.
+
+3. **Block tie-break in remediation**: `fix` > `recommended_version` > other blocks.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NamedTuple, Optional
+
+from cleanlib_sdk.reason_codes import ReasonCode
+
+Status = Literal["ALLOW", "WARN", "DENY"]
+
+
+class StatusResult(NamedTuple):
+    status: Status
+    reason_code: ReasonCode
+
+
+def _get(d: Optional[dict[str, Any]], key: str) -> Any:
+    if d is None:
+        return None
+    return d.get(key)
+
+
+def derive_status(envelope: dict[str, Any]) -> StatusResult:
+    """Apply the substance-precedence + freshness-override rule.
+
+    Accepts a parsed `VerdictEnvelopeV1` dict. Returns `(status, reason_code)`.
+
+    Empirical contract: identical output across all 4 SDK implementations for
+    every fixture in `cleanlib-contract-fixtures` v1.0.0.
+    """
+    rich = envelope.get("rich_data") or {}
+    rem = envelope.get("remediation") or {}
+    exp = envelope.get("exploitability") or {}
+    avail = envelope.get("availability") or {}
+
+    # Substance precedence — first match wins. Each branch also captures the
+    # `freshness_signal` (the substrate availability tag for the driving signal)
+    # so the freshness-override step can rewrite the reason_code without
+    # disturbing the status tier.
+    status: Status
+    reason: ReasonCode
+    freshness_signal: Optional[str] = None
+
+    if exp.get("exploitation_likelihood") == "CRITICAL":
+        status, reason = "DENY", ReasonCode.VERDICT_EXPLOITATION_CRITICAL
+        freshness_signal = avail.get("exploitation_fusion")
+    elif (
+        exp.get("in_kev")
+        and avail.get("kev") == "available"
+        and (exp.get("exploit_risk_score") or 0) >= 70
+    ):
+        status, reason = "DENY", ReasonCode.VERDICT_KEV_LISTED
+        freshness_signal = avail.get("kev")
+    elif rich.get("has_obfuscation"):
+        status, reason = "DENY", ReasonCode.VERDICT_OBFUSCATED
+    elif rem.get("fix") is not None or rem.get("recommended_version") is not None:
+        status, reason = "WARN", ReasonCode.VERDICT_HAS_REMEDIATION
+        # Block tie-break: fix > recommended_version > other blocks
+        block = rem.get("fix") or rem.get("recommended_version") or {}
+        freshness_signal = block.get("availability") if isinstance(block, dict) else None
+    elif (rich.get("abandonment_score") or 0) >= 0.7:
+        status, reason = "WARN", ReasonCode.VERDICT_ABANDONED
+    elif rich.get("recommended_version") is not None:
+        status, reason = "ALLOW", ReasonCode.VERDICT_RECOMMENDED_VERSION_NEWER
+    else:
+        status, reason = "ALLOW", ReasonCode.VERDICT_CLEAN
+
+    # Freshness override: keep status tier, rewrite reason_code.
+    if freshness_signal == "degraded_stale":
+        reason = ReasonCode.VERDICT_DEGRADED_STALE
+
+    return StatusResult(status=status, reason_code=reason)

cleanlib_sdk/errors.py

@@ -0,0 +1,119 @@
+"""CleanLibraryError hierarchy — mirrors cleanlib-client::errors per
+App Rev 4 §9.2 reason-code enum surfaced via X-CleanLibrary-Reason."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class CleanLibraryError(Exception):
+    """Base for all CleanLibrary SDK errors. Mirrors Rust cleanlib-client
+    CleanLibraryError enum."""
+
+    def __init__(self, message: str, reason_code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.reason_code = reason_code
+
+    def is_retryable(self) -> bool:
+        """True if a transient retry could plausibly succeed."""
+        return False
+
+
+class PolicyDenyError(CleanLibraryError):
+    """403 + POLICY_DENY_VERDICT / POLICY_DENY_RULE_EXPLICIT, or 451."""
+
+
+class IntegrityFailureError(CleanLibraryError):
+    """403 + INTEGRITY_FAILURE — package hash mismatch on serve path."""
+
+
+class RateLimitExceededError(CleanLibraryError):
+    """429 + Retry-After header."""
+
+    def __init__(self, message: str, retry_after_seconds: int = 60) -> None:
+        super().__init__(message, reason_code="RATE_LIMITED")
+        self.retry_after_seconds = retry_after_seconds
+
+    def is_retryable(self) -> bool:
+        return True
+
+
+class RiskAcceptanceRequiredError(CleanLibraryError):
+    """403 + RISK_ACCEPTANCE_REQUIRED — policy permits ALLOW but customer
+    hasn't signed risk-acceptance for this package/version."""
+
+    def __init__(
+        self,
+        message: str,
+        reason_code: str = "RISK_ACCEPTANCE_REQUIRED",
+        guidance: Optional[str] = None,
+        docs_url: Optional[str] = "https://docs.cleanlibrary.io/risk-acceptance",
+    ) -> None:
+        super().__init__(message, reason_code=reason_code)
+        self.guidance = guidance
+        self.docs_url = docs_url
+
+
+class AuthenticationError(CleanLibraryError):
+    """401, or 403 + KEY_INVALID / KEY_EXPIRED / KEY_SCOPE_INSUFFICIENT."""
+
+
+class InsufficientDataError(CleanLibraryError):
+    """403 + INSUFFICIENT_DATA_FAIL_CLOSED — verdict unavailable + customer
+    policy fails closed on missing data."""
+
+
+class PackageNotFoundError(CleanLibraryError):
+    """404 — package not in catalog + ingest declined or unavailable."""
+
+
+class ServerError(CleanLibraryError):
+    """5xx — server error. Retryable on 502/503/504."""
+
+    def __init__(self, message: str, status: int, reason_code: Optional[str] = None) -> None:
+        super().__init__(message, reason_code=reason_code)
+        self.status = status
+
+    def is_retryable(self) -> bool:
+        return self.status in (502, 503, 504)
+
+
+class TransportError(CleanLibraryError):
+    """Network / TLS / timeout / DNS — pre-response transport-layer failure."""
+
+    def is_retryable(self) -> bool:
+        return True
+
+
+class ParseError(CleanLibraryError):
+    """Response body parse failure (malformed JSON, schema mismatch)."""
+
+
+def from_http(status: int, reason_code: Optional[str], message: str, retry_after: Optional[int] = None) -> CleanLibraryError:
+    """Map HTTP status + X-CleanLibrary-Reason header into a typed exception.
+
+    Mirrors cleanlib-client::errors::from_http with the same dispatch table.
+    """
+    code = reason_code or "UNKNOWN"
+    body = message if message else f"HTTP {status}"
+
+    if status == 401:
+        return AuthenticationError(body, reason_code=code)
+    if status == 403 and code in ("KEY_INVALID", "KEY_EXPIRED", "KEY_SCOPE_INSUFFICIENT"):
+        return AuthenticationError(body, reason_code=code)
+    if (status == 403 and code in ("POLICY_DENY_VERDICT", "POLICY_DENY_RULE_EXPLICIT")) or status == 451:
+        return PolicyDenyError(body, reason_code=code)
+    if status == 403 and code == "RISK_ACCEPTANCE_REQUIRED":
+        return RiskAcceptanceRequiredError(body, reason_code=code)
+    if status == 403 and code == "INTEGRITY_FAILURE":
+        return IntegrityFailureError(body, reason_code=code)
+    if status == 403 and code == "INSUFFICIENT_DATA_FAIL_CLOSED":
+        return InsufficientDataError(body, reason_code=code)
+    if status == 429:
+        return RateLimitExceededError(body, retry_after_seconds=retry_after or 60)
+    if status == 404:
+        return PackageNotFoundError(body, reason_code=code)
+    if 500 <= status <= 599:
+        return ServerError(body, status=status, reason_code=code)
+    return ServerError(body, status=status, reason_code=code)

cleanlib_sdk/http/__init__.py

@@ -0,0 +1,30 @@
+"""Per-domain HTTP clients (sdk-js v0.4.1 sister-shape).
+
+v0.4.1 introduces the per-domain client split alongside the existing
+`cleanlib_sdk.client.Client` (which becomes deprecated; full removal in v1.0.0).
+
+| Client | Domain | Endpoint default |
+|---|---|---|
+| `HttpRemediationClient` | sparse 7-block /remediation responses | vva URL (per F4 ratification; v0.4.2 flips to cleanlib-enrich) |
+| (HttpVerdictClient / HttpEnrichClient — v0.4.2 ripple) | | |
+"""
+
+from cleanlib_sdk.http.remediation_client import (
+    DEFAULT_REMEDIATION_BASE_URL,
+    REMEDIATION_CACHE_TTL_SECS,
+    HttpRemediationClient,
+)
+from cleanlib_sdk.http.types import (
+    RemediationBlock,
+    RemediationOrAbsent,
+    RemediationResponse,
+)
+
+__all__ = [
+    "HttpRemediationClient",
+    "DEFAULT_REMEDIATION_BASE_URL",
+    "REMEDIATION_CACHE_TTL_SECS",
+    "RemediationBlock",
+    "RemediationResponse",
+    "RemediationOrAbsent",
+]