npm

Documentation

Overview

The full specification for the API endpoints can be found at: https://github.com/npm/registry/blob/master/docs/REGISTRY-API.md

Index

• Constants
• Variables
• func NewNPMPublicKeyVerifier(ctx context.Context, npm *Client, trustedRoot *root.TrustedRoot) (*verify.SignedEntityVerifier, error)
• type Attestation
• type AttestationBundle
• type Client
  • func (c *Client) GetAttestations(ctx context.Context, name, version string) ([]AttestationBundle, error)
  • func (c *Client) GetPackage(ctx context.Context, name string) (*Package, error)
  • func (c *Client) GetPackageVersion(ctx context.Context, name, version string) (*PackageVersion, error)
  • func (c *Client) GetPublicKeys(ctx context.Context) ([]Key, error)
• type Dist
• type DistTags
• type Key
• type Maintainer
• type Package
• type PackageVersion
• type Provenance
• type Repository
  • func (r *Repository) UnmarshalJSON(data []byte) error
• type Signature
• type User
• type VerificationStatus
• type Verifier
  • func NewVerifier(ctx context.Context, npm *Client) (*Verifier, error)
  • func (v *Verifier) Verify(ctx context.Context, pkg *PackageVersion) (*VerificationStatus, error)

Examples

• Verifier.Verify

Constants

const Host = "registry.npmjs.org"

Variables

var (
	ErrMissingSHA512Digest = errors.New("sha512 digest not found for package's version")
	ErrMissingPublicKeys   = errors.New("no public keys returned by NPM")
)

Functions

func NewNPMPublicKeyVerifier

func NewNPMPublicKeyVerifier(
	ctx context.Context,
	npm *Client,
	trustedRoot *root.TrustedRoot,
) (*verify.SignedEntityVerifier, error)

Types

type Attestation

type Attestation struct {
	URL        string     `json:"url"`
	Provenance Provenance `json:"attestation"`
}

type AttestationBundle

type AttestationBundle struct {
	PredicateType string         `json:"predicateType"`
	Bundle        *bundle.Bundle `json:"bundle"`
}

type Client

type Client struct {
	HTTP *http.Client
}

func (*Client) GetAttestations

func (c *Client) GetAttestations(ctx context.Context, name, version string) ([]AttestationBundle, error)

func (*Client) GetPackage

func (c *Client) GetPackage(ctx context.Context, name string) (*Package, error)

func (*Client) GetPackageVersion

func (c *Client) GetPackageVersion(ctx context.Context, name, version string) (*PackageVersion, error)

func (*Client) GetPublicKeys

func (c *Client) GetPublicKeys(ctx context.Context) ([]Key, error)

type Dist

type Dist struct {
	Integrity    string      `json:"integrity"`
	Shasum       string      `json:"shasum"`
	Tarball      string      `json:"tarball"`
	FileCount    int         `json:"fileCount"`
	UnpackedSize int         `json:"unpackedSize"`
	Signatures   []Signature `json:"signatures"`
	Attestations Attestation `json:"attestations"`
	NpmSignature string      `json:"npm-signature"`
}

type DistTags

type DistTags struct {
	Latest string `json:"latest"`
}

type Key

type Key struct {
	Expires *string `json:"expires"`
	KeyID   string  `json:"keyid"`
	KeyType string  `json:"keytype"`
	Scheme  string  `json:"scheme"`
	Key     string  `json:"key"`
}

type Maintainer

type Maintainer struct {
	Name     string `json:"name"`
	Username string `json:"username"`
	Email    string `json:"email"`
}

type Package

type Package struct {
	ID             string                    `json:"_id"`
	Rev            string                    `json:"_rev"`
	Name           string                    `json:"name"`
	Description    string                    `json:"description"`
	DistTags       DistTags                  `json:"dist-tags"`
	Versions       map[string]PackageVersion `json:"versions"`
	Readme         string                    `json:"readme"`
	Maintainers    []Maintainer              `json:"maintainers"`
	Time           map[string]time.Time      `json:"time"`
	ReadmeFilename string                    `json:"readmeFilename"`
	Keywords       []string                  `json:"keywords"`
	Users          map[string]bool           `json:"users"`
	Homepage       string                    `json:"homepage"`
}

type PackageVersion

type PackageVersion struct {
	Name            string            `json:"name"`
	Description     string            `json:"description"`
	Version         string            `json:"version"`
	Repository      Repository        `json:"repository"`
	Dependencies    map[string]string `json:"dependencies"`
	DevDependencies map[string]string `json:"devDependencies"`
	GitHead         string            `json:"gitHead"`
	ID              string            `json:"_id"`
	NodeVersion     string            `json:"_nodeVersion"`
	NpmVersion      string            `json:"_npmVersion"`
	Dist            Dist              `json:"dist"`
	NpmUser         User              `json:"_npmUser"`
	HasShrinkwrap   bool              `json:"_hasShrinkwrap"`
}

Some additional fields exist but they can have multiple types. This causes errors at json.Unmarshal time if the field does not have the righ type. There are simply excluded them from the struct for now as they are not used elsewhere in the code.

type Provenance

type Provenance struct {
	PredicateType string `json:"predicateType"`
}

type Repository

type Repository struct {
	Type string `json:"type"`
	URL  string `json:"url"`
}

func (*Repository) UnmarshalJSON

func (r *Repository) UnmarshalJSON(data []byte) error

The `Repository` field in `PackageVersion` can have multiple types.

type Signature

type Signature struct {
	Keyid string `json:"keyid"`
	Sig   string `json:"sig"`
}

type User

type User struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

type VerificationStatus

type VerificationStatus struct {
	URL              string
	SHA512           string
	InferredIssuer   string
	HasAttestations  bool
	Attestation      *verify.VerificationResult
	AttestationError error
	Provenance       *verify.VerificationResult
	ProvenanceError  error
}

type Verifier

type Verifier struct {
	NPM          *Client
	SigStore     *verify.SignedEntityVerifier
	NPMPublicKey *verify.SignedEntityVerifier
}

func NewVerifier

func NewVerifier(ctx context.Context, npm *Client) (*Verifier, error)

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, pkg *PackageVersion) (*VerificationStatus, error)

Example

package main

import (
	"context"
	"log"

	"github.com/DataDog/go-attestations-verifier/internal/httputil"
	"github.com/DataDog/go-attestations-verifier/pkg/npm"
)

func main() {
	ctx := context.Background()

	npmClient := &npm.Client{HTTP: httputil.DefaultClient()}

	pkg, err := npmClient.GetPackageVersion(ctx, "sigstore", "3.0.0")
	if err != nil {
		log.Fatal(err)
	}

	verifier, err := npm.NewVerifier(ctx, npmClient)
	if err != nil {
		log.Fatal(err)
	}

	status, err := verifier.Verify(ctx, pkg)
	if err != nil {
		log.Fatal(err)
	}

	log.Print(status)
}