pkg-proxy/supporting-module-issues.md

Package repository support issues

These drafts are grouped by the repository where the work belongs. The proxy issues are already open. The remaining drafts have not been posted.

Helm, Chef, and Vagrant are listed as candidate PURL types. Helm has an open upstream pull request, while Chef and Vagrant still need upstream type definitions. Their registry clients should follow the accepted definitions when exposing package identities through shared APIs.

git-pkgs/proxy

Already open:

• #261 Add Helm repository proxy support
• #262 Add Alpine APK repository proxy support
• #263 Add Arch Linux package repository proxy support
• #264 Add Chef Supermarket proxy support
• #265 Add Vagrant box repository proxy support

package-url/purl-spec

Helm type work is already open as #236. The pull request needs to be updated to the current JSON type-definition format. Do not open a second Helm proposal.

Define the Chef PURL type

Chef is listed as a candidate PURL type, but it has no type definition or tracking issue.

Define how Chef cookbooks map to PURL components. Cover cookbook names, versions, Supermarket hosts, private Supermarket instances, and source repositories. Include type tests and examples for the public Supermarket and a configured private server.

Define the Vagrant PURL type

Vagrant is listed as a candidate PURL type, but it has no type definition or tracking issue.

Define how Vagrant boxes map to PURL components. Cover namespaces, box names, versions, providers, architectures, catalog URLs, and checksums. Include type tests and examples for Vagrant Cloud and a configured private catalog.

git-pkgs/purl

Add Helm, Chef, and Vagrant PURL type support

The upstream specification lists Helm, Chef, and Vagrant as candidate types. Helm has an open type proposal, while Chef and Vagrant still need definitions.

After each definition is accepted upstream, add it to the local type catalog and implement any required normalization, validation, version handling, and OSV mappings. Add construction, parsing, normalization, and round-trip tests using the upstream examples.

git-pkgs/manifests

Add Helm chart manifest and lockfile support

Add parsers for Chart.yaml and Chart.lock.

Chart.yaml should report the chart name, version, declared dependencies, repository URLs, and dependency version constraints. Chart.lock should report the resolved dependency set and digest without treating the generated timestamp as package identity.

Tests should cover aliased repositories, OCI repository URLs, conditions, tags, and charts with no dependencies.

Add Chef cookbook manifest support

Add static parsers for Chef metadata.rb and Berksfile files. Do not execute Ruby while parsing them.

The metadata parser should report the cookbook name, version, license, and depends declarations. The Berksfile parser should report cookbook sources, version constraints, and git or path sources when they are static string literals.

Tests should cover unconstrained dependencies, pessimistic constraints, custom Supermarket sources, and dynamic Ruby expressions that must be skipped without failing the whole file.

Add Vagrant box declarations from Vagrantfile

Add a static Vagrantfile parser for box dependencies. Do not execute the Ruby configuration file.

Recognize literal values assigned to config.vm.box, box_version, box_url, box_download_checksum, and box_download_checksum_type. Return the box as a direct dependency with its version, source URL, and integrity metadata when available.

Tests should cover namespaced boxes, version constraints, custom catalog URLs, checksums, and dynamic expressions that cannot be resolved safely.

Alpine APKBUILD and Arch PKGBUILD parsing already exist, so they do not need new manifest issues.

git-pkgs/registries

Add Helm HTTP repository metadata support

Add a registry client for HTTP Helm repositories backed by index.yaml.

Map charts and chart releases to the shared package and version types. Include creation time, digest, deprecation status, home and source links, dependencies, maintainers, and absolute or relative artifact URLs when those fields are present.

Require a configured repository URL because Helm has no single default HTTP repository. Tests should cover multiple chart versions, relative URLs, deprecated charts, missing optional fields, and custom authenticated repositories.

This issue depends on an accepted Helm PURL type definition. Track purl-spec#236.

Add OCI registry metadata support

Add a registry client for pkg:oci packages. Support tag listing, manifest retrieval by tag or digest, OCI indexes, annotations, and Bearer authentication challenges.

Preserve the artifact type and layer media types so callers can distinguish container images, Helm charts, and other OCI artifacts. Tests should include the Helm config and chart layer media types as well as ordinary image manifests.

Add Alpine APK repository metadata support

Add an apk registry client for configured Alpine repositories. There is no single default repository, so repository_url should identify a concrete release, repository, and architecture location.

Read package names, versions, descriptions, licenses, dependencies, build times, maintainers, architectures, and checksums from v2 APKINDEX.tar.gz and v3 Packages.adb indexes. Keep namespace handling compatible with standard pkg:apk PURLs.

Tests should cover v2 and v3 indexes, multiple architectures, versioned PURLs, missing optional fields, and authenticated repositories.

Add Arch Linux repository metadata support

Add an alpm registry client for configured pacman repositories. There is no single default repository, so repository_url should identify the repository and architecture location.

Parse repository database entries into package metadata, versions, dependencies, licenses, build dates, packagers, architectures, and SHA-256 checksums. Keep namespace handling compatible with standard pkg:alpm PURLs.

Tests should cover compressed repository databases, epoch and package-release versions, architecture qualifiers, missing optional fields, and authenticated repositories.

Add Chef Supermarket registry support

Add a Chef Supermarket registry client using /universe and the cookbook API.

Return cookbook metadata, available versions, publication times, dependencies, maintainers, source links, and versioned download locations. Support the public Supermarket and configured private Supermarket servers.

Tests should cover dependency graphs, version metadata, custom base URLs, authentication, redirects, and missing cookbooks.

This issue depends on an accepted Chef PURL type definition.

Add Vagrant box catalog registry support

Add a Vagrant registry client that reads box catalog metadata and supports Vagrant Cloud catalog responses.

Return box descriptions, versions, providers, architectures, download URLs, checksums, and release timestamps when available. Support custom catalog URLs and configured credentials.

Tests should cover multiple providers and architectures, legacy catalog entries without architecture fields, checksum types, redirects, private catalogs, and missing boxes.

This issue depends on an accepted Vagrant PURL type definition.

git-pkgs/archives

Handle real Alpine APK v2 and v3 packages

The archive reader currently routes Alpine .apk files to the shared gzip and tar reader. Signed APK v2 packages contain concatenated gzip streams for the signature, control metadata, and payload. A standard tar reader stops after the first tar stream, so it cannot reliably browse or extract the package payload. APK v3 adds the ADB format.

Add format-aware APK readers that expose package metadata and payload files without confusing Android APK ZIP files. Preserve the existing decompression and path safety limits.

Tests should use signed v2 and v3 fixtures and cover listing, extraction, malformed stream boundaries, decompression limits, and Android APK detection.

Arch .pkg.tar.zst support is already tracked by archives#23, so do not open a duplicate zstd issue. Helm charts, Chef cookbooks, and Vagrant boxes use physical archive formats the module can already detect.

git-pkgs/magic

Detect Alpine APK v3 ADB data

Add byte-signature detection for Alpine APK v3 ADB indexes and packages. Keep the result at the physical format level, consistent with the existing gzip, zstd, tar, and ZIP classifications.

Tests should cover valid ADB prefixes, short input, malformed headers, and nearby byte sequences that must remain unclassified.

git-pkgs/integrity

Add verification-only MD5 and SHA-1 checksums

Vagrant box catalogs may publish MD5 or SHA-1 checksums as well as SHA-256, SHA-384, and SHA-512. Add MD5 and SHA-1 algorithms for checking bytes against publisher-supplied metadata.

Keep the weak algorithms out of SRI parsing and formatting, and document that they are provided only for compatibility verification. They must not be selected for newly generated integrity metadata when a stronger algorithm is available.

Add reader, hexadecimal parsing, length validation, verification, and failure tests for both algorithms.

git-pkgs/managers

These command definitions are useful for client integration and broader tool support, but they do not block the proxy handlers.

Add apk package manager commands

Add an apk manager definition for Alpine packages. Cover install, add, remove, list, outdated, update, resolve, and path operations where apk exposes a suitable command.

Tests should verify generated commands, repository arguments, versioned packages, non-interactive flags, and operations that require elevated permissions.

Add pacman package manager commands

Add a pacman manager definition for Arch packages. Cover install, add, remove, list, outdated, update, resolve, and path operations where pacman exposes a suitable command.

Tests should verify generated commands, repository refresh behavior, versioned packages, non-interactive flags, and operations that require elevated permissions.

Add Berkshelf commands

Add a berks manager definition for Chef cookbook dependencies. Cover install, list, outdated, update, resolve, and vendor operations.

Tests should verify generated commands, frozen or locked installs, custom Berksfile paths, and JSON or machine-readable output where Berkshelf provides it.

Add Vagrant box commands

Add a vagrant manager definition for box operations. Cover box add, remove, list, outdated, update, and path operations where Vagrant exposes a suitable command.

Tests should verify namespaced boxes, versions, providers, architectures, custom catalog URLs, checksums, and non-interactive flags.

Helm manager support already exists.

git-pkgs/enrichment

Expose new package registry clients through enrichment

After the registry clients and PURL conventions land, update enrichment to expose metadata for Helm, Alpine, Arch, Chef, and Vagrant packages through the direct and hybrid clients.

Add dependency updates and conversion tests for package metadata, versions, publication times, integrity values, status fields, and custom repository_url values. Alpine and Arch vulnerability PURL translation already exists and should remain covered.

This issue should wait until the corresponding registries work is available.