Architecture

CleanLibrary is a verdict-attested package proxy. Your package managers fetch artifacts through CleanLibrary instead of directly from the upstream registry; CleanLibrary serves the same artifact bytes as upstream and attaches signed metadata describing whether the package is judged safe under your policy.

Request flow

   Your package          ┌──────────────────────────────────────────┐
   manager               │              CleanLibrary                 │
   (npm / pip /          │                                            │
    go / cargo)          │   ┌──────────────┐    ┌─────────────────┐ │
        │                │   │ Ecosystem     │   │ Policy          │ │
        └──── HTTPS ──────┼──▶│ protocol     │──▶│ evaluator        │ │
                         │   │ handlers      │   └─────────────────┘ │
                         │   └──────┬───────┘            │           │
                         │          │                    │           │
                         │   ┌──────▼───────┐    ┌────────▼────────┐ │
                         │   │ Package       │   │ Verdict + policy │ │
                         │   │ catalog       │   │ cache            │ │
                         │   └──────────────┘    └─────────────────┘ │
                         │          │                    │           │
                         │   ┌──────▼─────────────────────▼────────┐ │
                         │   │ Cosign attestation on every response │ │
                         │   └──────────────────────────────────────┘ │
                         └────────────────────────────────────────────┘
                                          │              │
                                   verdict│       policy │
                                          ▼              ▼
                                  ┌──────────────┐ ┌──────────────┐
                                  │ Verdict       │ │ Your policy  │
                                  │ engine        │ │ (admin UI)   │
                                  └──────────────┘ └──────────────┘

1. Fetch — your package manager requests a package through CleanLibrary's ecosystem endpoint over HTTPS, authenticated with your organization's Bearer token.
2. Serve — CleanLibrary returns the upstream artifact bytes from its catalog, unchanged.
3. Judge — alongside the bytes, CleanLibrary attaches a verdict (ALLOW / DENY / WARN) from the analysis engine, evaluated against your organization's policy.
4. Attest — every response carries a cosign attestation binding the verdict and policy decision, so the result is independently verifiable.

Verdict + policy

• Verdict — each package version carries an analysis verdict with reasoning, confidence, and supporting signals (such as a recommended upgrade version, package-risk summary, and typo-squat indicators when available).
• Policy — you author the policy that maps verdicts to enforcement outcomes for your organization, using a predicate language (e.g. verdict source, freshness, and risk thresholds).
• Risk acceptance — for packages you must keep despite a DENY/WARN, an explicit, audited risk-acceptance workflow records the decision rather than silently bypassing it.

Attestation

Every served artifact carries a cosign attestation that binds the verdict_id, policy_decision, risk_acceptance_status, application version, and serve timestamp. Your compliance team can verify the attestation and extract it as SBOM material. Contact CleanStart for the published verification key.

Performance + reliability

• Catalog — packages are mirrored on first request and served from a content-addressed catalog thereafter, with upstream integrity verification on ingest.
• Caching — verdicts and policy decisions are cached in-process and in a shared cache tier to keep the request path fast.
• Offline fallback — clients (CLI, SDKs, IDE extension) fall back to local fixtures and surface a clear status when the backend is unreachable, so evaluation never hard-fails.

Supported ecosystems

Ecosystem	Endpoint family
npm	/npm/... (including scoped packages)
PyPI	/pypi/simple/... + /pypi/packages/...
Go	/go/... (GOPROXY)
crates	/crates/...

Client surfaces

• CLI — cleanlib with verbs for verdict, scan, policy preview, audit, fetch, risk-accept, and proxy-config emission for your package managers.
• SDKs — JavaScript/TypeScript, Python, and Go libraries for programmatic verdict + policy access.
• MCP server — exposes verdict and attestation lookups to MCP-compatible AI tooling.
• VS Code extension — inline ALLOW/DENY/WARN decisions, rich-data hover, and one-click risk-acceptance rule generation in the editor.

See Getting Started to install a client and configure your token.