npm

Documentation

Overview

Package npm resolves manifest entries against the npm registry, anchoring per-file integrity to the registry-published tarball hash.

Index

• Constants
• Variables
• func IsSticky(lockedVersion, constraint string) bool
• type Attestation
• type ConstraintKind
  • func Classify(constraint string) ConstraintKind
• type Options
• type PackageStatus
• type Resolved
• type ResolvedFile
• type SignatureMode
• type Source
  • func New(opts Options) *Source
  • func (s *Source) Resolve(ctx context.Context, p *purl.PURL, files []string) (*Resolved, error)
  • func (s *Source) ResolveVersion(ctx context.Context, p *purl.PURL, constraint string, cool *cooldown.Config) (string, error)
  • func (s *Source) Status(ctx context.Context, p *purl.PURL) (*PackageStatus, error)

Constants

const (
	DefaultRegistryURL     = "https://registry.npmjs.org"
	DefaultMaxTarballBytes = 100 << 20 // 100 MiB

)

Variables

var ErrUnsafeTarballEntry = errors.New("tarball contains non-regular file entry")

ErrUnsafeTarballEntry surfaces non-regular tar entries (symlink, hardlink, device, fifo). A symlink entry would extract as a zero-byte regular file via the standard tar reader, letting a publisher ship "empty bytes with valid integrity" in place of the claimed asset.

Functions

func IsSticky

func IsSticky(lockedVersion, constraint string) bool

IsSticky reports whether the locked version still satisfies the constraint and can be reused without re-resolving. Dist-tags are never sticky — the tag can move under a stable manifest.

Types

type Attestation

type Attestation = source.Attestation

type ConstraintKind

type ConstraintKind int

const (
	KindExact ConstraintKind = iota
	KindRange
	KindDistTag
)

func Classify

func Classify(constraint string) ConstraintKind

Classify maps a manifest version string to exact / range / dist-tag.

type Options

type Options struct {
	RegistryURL     string
	MaxTarballBytes int64
	HTTPClient      *client.Client

	// Verifier validates each attestation bundle the npm path records.
	// Nil = record-only; a non-nil verifier promotes attestations to a
	// hard fetch dependency.
	Verifier source.ProvenanceVerifier

	SignatureMode SignatureMode
	// contains filtered or unexported fields
}

type PackageStatus

type PackageStatus struct {
	Latest              string
	LatestTime          string
	LastPublish         string
	Deprecated          string
	Yanked              bool
	License             string
	LatestLicense       string
	LockedHasProvenance bool
	LatestHasProvenance bool
}

type Resolved

type Resolved = source.Resolved

type ResolvedFile

type ResolvedFile = source.ResolvedFile

type SignatureMode

type SignatureMode int

SignatureMode selects how strictly dist.signatures is verified.

const (
	// SignatureModeWarn (default) verifies when a signature is present;
	// fails on a bad signature; warns when missing.
	SignatureModeWarn SignatureMode = iota
	// SignatureModeEnforce additionally fails when no signature is present.
	SignatureModeEnforce
	// SignatureModeOff skips signature verification entirely.
	SignatureModeOff
)

type Source

type Source struct {
	// contains filtered or unexported fields
}

func New

func New(opts Options) *Source

func (*Source) Resolve

func (s *Source) Resolve(ctx context.Context, p *purl.PURL, files []string) (*Resolved, error)

Resolve fetches the named files for the package identified by p (whose Type must be "npm"). When files is nil, the package's declared entry point is used.

func (*Source) ResolveVersion

func (s *Source) ResolveVersion(ctx context.Context, p *purl.PURL, constraint string, cool *cooldown.Config) (string, error)

ResolveVersion turns a manifest constraint into an exact version. Exact pins bypass cooldown. Ranges fall back to the next-highest satisfying version outside the window. Dist-tags inside the window error rather than silently picking an older version. cool may be nil to disable cooldown. p's repository_url qualifier, if present, overrides the Source's default registry for this call.

func (*Source) Status

func (s *Source) Status(ctx context.Context, p *purl.PURL) (*PackageStatus, error)

Status reports registry-side signals for a locked version. p.Version is the locked version to look up. p's repository_url qualifier, if present, overrides the Source's default registry.