npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@actions/attest

v1.5.0

Published

Actions attestation lib

Downloads

13,714

Readme

@actions/attest

Functions for generating signed attestations for workflow artifacts.

Attestations bind some subject (a named artifact along with its digest) to a predicate (some assertion about that subject) using the in-toto statement format. A signature is generated for the attestation using a Sigstore-issued signing certificate.

Once the attestation has been created and signed, it will be uploaded to the GH attestations API and associated with the repository from which the workflow was initiated.

See Using artifact attestations to establish provenance for builds for more information on artifact attestations.

Usage

attest

The attest function takes the supplied subject/predicate pair and generates a signed attestation.

const { attest } = require('@actions/attest');
const core = require('@actions/core');

async function run() {
    // In order to persist attestations to the repo, this should be a token with
    // repository write permissions.
    const ghToken = core.getInput('gh-token');

    const attestation = await attest({
        subjects: [{name: 'my-artifact-name', digest: { 'sha256': '36ab4667...'}}],
        predicateType: 'https://in-toto.io/attestation/release',
        predicate: { . . . },
        token: ghToken
    });

    console.log(attestation);
}

run();

The attest function supports the following options:

export type AttestOptions = {
  // Deprecated. Use 'subjects' instead.
  subjectName?: string
  // Deprecated. Use 'subjects' instead.
  subjectDigest?: Record<string, string>
  // Collection of subjects to be attested
  subjects?: Subject[]
  // URI identifying the content type of the predicate being attested.
  predicateType: string
  // Predicate to be attested.
  predicate: object
  // GitHub token for writing attestations.
  token: string
  // Sigstore instance to use for signing. Must be one of "public-good" or
  // "github".
  sigstore?: 'public-good' | 'github'
  // HTTP headers to include in request to attestations API.
  headers?: {[header: string]: string | number | undefined}
  // Whether to skip writing the attestation to the GH attestations API.
  skipWrite?: boolean
}

export type Subject = {
   // Name of the subject.
  name: string
   // Digests of the subject. Should be a map of digest algorithms to their hex-encoded values.
  digest: Record<string, string>
}

attestProvenance

The attestProvenance function accepts the name and digest of some artifact and generates a build provenance attestation over those values.

The attestation is formed by first generating a SLSA provenance predicate populated with metadata pulled from the GitHub Actions run.

const { attestProvenance } = require('@actions/attest');
const core = require('@actions/core');

async function run() {
    // In order to persist attestations to the repo, this should be a token with
    // repository write permissions.
    const ghToken = core.getInput('gh-token');

    const attestation = await attestProvenance({
        subjectName: 'my-artifact-name',
        subjectDigest: { 'sha256': '36ab4667...'},
        token: ghToken
    });

    console.log(attestation);
}

run();

The attestProvenance function supports the following options:

export type AttestProvenanceOptions = {
  // Deprecated. Use 'subjects' instead.
  subjectName?: string
  // Deprecated. Use 'subjects' instead.
  subjectDigest?: Record<string, string>
  // Collection of subjects to be attested
  subjects?: Subject[]
  // URI identifying the content type of the predicate being attested.
  token: string
  // Sigstore instance to use for signing. Must be one of "public-good" or
  // "github".
  sigstore?: 'public-good' | 'github'
  // HTTP headers to include in request to attestations API.
  headers?: {[header: string]: string | number | undefined}
  // Whether to skip writing the attestation to the GH attestations API.
  skipWrite?: boolean
  // Issuer URL responsible for minting the OIDC token from which the
  // provenance data is read. Defaults to
  // 'https://token.actions.githubusercontent.com".
  issuer?: string
}

Attestation

The Attestation returned by attest/attestProvenance has the following fields:

export type Attestation = {
  /*
   * JSON-serialized Sigstore bundle containing the provenance attestation,
   * signature, signing certificate and witnessed timestamp.
   */
  bundle: SerializedBundle
  /*
   * PEM-encoded signing certificate used to sign the attestation.
   */
  certificate: string
  /*
   * ID of Rekor transparency log entry created for the attestation (if
   * applicable).
   */
  tlogID?: string
  /*
   * ID of the persisted attestation (accessible via the GH API).
   */
  attestationID?: string
}

For details about the Sigstore bundle format, see the Bundle protobuf specification.

Sigstore Instance

When generating the signed attestation there are two different Sigstore instances which can be used to issue the signing certificate. By default, workflows initiated from public repositories will use the Sigstore public-good instance and persist the attestation signature to the public Rekor transparency log. Workflows initiated from private/internal repositories will use the GitHub-internal Sigstore instance which uses a signed timestamp issued by GitHub's timestamp authority in place of the public transparency log.

The default Sigstore instance selection can be overridden by passing an explicit value of either "public-good" or "github" for the sigstore option when calling either attest or attestProvenance.

Storage

Attestations created by attest/attestProvenance will be uploaded to the GH attestations API and associated with the appropriate repository. Attestation storage is only supported for public repositories or repositories which belong to a GitHub Enterprise Cloud account.

In order to generate attestations for private, non-Enterprise repositories, the skipWrite option should be set to true.