registry

Documentation

Overview

Package registry checks whether packages exist on their public registry. Automatic evidence collection is allowed only for PUBLIC packages (goal.md §8.1); any failure to determine publicness yields UNKNOWN, which downstream code treats as private — the safe default.

Index

• func ValidPackageName(ecosystem, name string) bool
• type Cache
• type Checker
  • func (c *Checker) CachedPublicness(ctx context.Context, p domain.PURL) (string, bool)
  • func (c *Checker) Check(ctx context.Context, p domain.PURL) string
  • func (c *Checker) CheckAll(ctx context.Context, pkgs []scanner.ResolvedPackage)
  • func (c *Checker) MavenHasJar(ctx context.Context, p domain.PURL) (hasJar, known bool)
• type ServerCache
  • func (s *ServerCache) GetPublicness(ctx context.Context, purl string) (string, time.Time, bool)
  • func (s *ServerCache) SetPublicness(ctx context.Context, purl, status string) error

Functions

func ValidPackageName

func ValidPackageName(ecosystem, name string) bool

ValidPackageName reports whether name has a safe public-registry shape.

It is deliberately a conservative common subset of the registries' name grammars. Public package names are ASCII and use unreserved path characters; only npm scopes, Composer coordinates and Go modules contain slashes, and each has a fixed shape. This is both input validation and a URL-boundary invariant: query delimiters, fragments, traversal elements and extra path segments can never be reinterpreted by net/http or a registry proxy.

Types

type Cache

type Cache interface {
	GetPublicness(ctx context.Context, purl string) (status string, checkedAt time.Time, ok bool)
	SetPublicness(ctx context.Context, purl, status string) error
}

Cache stores publicness verdicts keyed by canonical purl string. Implementations are expected to be backed by localdb.

type Checker

type Checker struct {
	Cache    Cache
	HTTP     *http.Client
	BaseURLs map[string]string // ecosystem → base URL override, mainly for tests
}

Checker resolves package publicness against the supported registries. Nine ecosystems have Public v1 verification adapters; Maven is deliberately A4 only, so this probe supports exact sample coordinates and Wanted without implying that arbitrary Java projects are scanned. The zero value uses the real registry endpoints, a 5s-timeout HTTP client, and no cache.

func (*Checker) CachedPublicness

func (c *Checker) CachedPublicness(ctx context.Context, p domain.PURL) (string, bool)

CachedPublicness answers from the cache alone, and reports whether it could.

It is the whole of Check's cache path, called by Check rather than duplicated beside it, so the validation and the TTL cannot drift between the two callers. A caller bounding outbound registry traffic asks this first: an answer from here reached nobody and must not be charged to that bound.

A PURL parser separates fields; it does not prove that the name has a valid shape for its registry. An unescaped '?' or '#' changes the meaning of a URL assembled from that name: an exact npm probe for "react?anything" would otherwise request /react and grade a made-up package PUBLIC. Validating before the cache read as well means an old poisoned verdict cannot bypass the corrected boundary.

func (*Checker) Check

func (c *Checker) Check(ctx context.Context, p domain.PURL) string

Check reports PUBLIC, PRIVATE, or UNKNOWN for p. It never blocks longer than the request timeout and never returns an error: any transport or server failure is UNKNOWN. Fresh cache entries (younger than 24h) are returned without a network call; UNKNOWN verdicts are never cached so the next call retries.

func (*Checker) CheckAll

func (c *Checker) CheckAll(ctx context.Context, pkgs []scanner.ResolvedPackage)

CheckAll upgrades the Publicness of UNKNOWN entries in place. PRIVATE entries are never queried (goal.md §25.E) and PUBLIC entries are left as-is.

func (*Checker) MavenHasJar

func (c *Checker) MavenHasJar(ctx context.Context, p domain.PURL) (hasJar, known bool)

MavenHasJar reports whether a maven coordinate publishes a compiled artifact, and whether the answer is known at all.

A BOM or a parent POM publishes only a pom: it declares versions for other modules and contains no classes, so there is no symbol a contract could call and no sample anyone could write. Measured on Maven Central, guava-parent, kotlin-gradle-plugins-bom and junit-bom all answer 404 for their jar and 200 for their pom.

The name cannot decide this. "-bom" and "-parent" are conventions authors choose, not a generated marker like Gradle's ".gradle.plugin", and a false exclusion loses real authoring work permanently and silently. So it asks.

The second return is the honesty: a network failure, an unparseable coordinate or a registry that answers neither way is "not known", and the caller must treat that as "carry on" rather than as "no jar".

type ServerCache

type ServerCache struct {
	Store serverstore.Store

	// Now is a test seam; nil means time.Now.
	Now func() time.Time
}

ServerCache adapts the serverstore packages table to the Cache interface, so the server-side ingest publicness gate (strict mode) reuses the exact same Checker the local client uses. Verdicts persist on packages.publicness with checked_at as the cache timestamp.

func (*ServerCache) GetPublicness

func (s *ServerCache) GetPublicness(ctx context.Context, purl string) (string, time.Time, bool)

GetPublicness returns the stored verdict for purl. A package row without a checked_at (evidence arrived but publicness was never verified) or with an UNKNOWN verdict is a cache miss, so the Checker re-queries the registry.

func (*ServerCache) SetPublicness

func (s *ServerCache) SetPublicness(ctx context.Context, purl, status string) error

SetPublicness upserts the verdict with the current time as checked_at.