@sigstore/sign

@sigstore/sign ·

A library for generating Sigstore signatures.

Features

• Support for keyless signature generation with Fulcio-issued signing certificates
• Support for ambient OIDC credential detection in CI/CD environments
• Support for recording signatures to the Rekor transparency log
• Support for requesting timestamped countersignature from a Timestamp Authority

Prerequisites

• Node.js version ^20.17.0 || >=22.9.0

Installation

npm install @sigstore/sign

Overview

This library provides the building blocks for composing custom Sigstore signing workflows.

BundleBuilder

The top-level component is the BundleBuilder which has responsibility for taking some artifact and returning a Sigstore bundle containing the signature for that artifact and the various materials necessary to verify that signature.

interface BundleBuilder {
  create: (artifact: Artifact) => Promise<Bundle>;
}

The artifact to be signed is simply an array of bytes and an optional mimetype. The type is necessary when the signature is packaged as a DSSE envelope.

type Artifact = {
  data: Buffer;
  type?: string;
};

There are two BundleBuilder implementations provided as part of this package:

• DSSEBundleBuilder - Combines the verification material and artifact signature into a dsse_envelope -style Sigstore bundle
• MessageBundleBuilder - Combines the verification material and artifact signature into a message_signature-style Sigstore bundle.

Signer

Every BundleBuilder must be instantiated with a Signer implementation. The Signer is responsible for taking a Buffer and returning an Signature.

interface Signer {
  sign: (data: Buffer) => Promise<Signature>;
}

The returned Signature contains a signature and the public key which can be used to verify that signature -- the key may either take the form of a x509 certificate or public key.

type Signature = {
  signature: Buffer;
  key: KeyMaterial;
};

type KeyMaterial =
  | {
      $case: 'x509Certificate';
      certificate: string;
    }
  | {
      $case: 'publicKey';
      publicKey: string;
      hint?: string;
    };

This package provides the FulcioSigner which implements the Signer interface and signs the artifact with an ephemeral keypair. It will also retrieve an OIDC token from the configured IdentityProvider and then request a signing certificate from Fulcio which binds the ephemeral key to the identity embedded in the token. This signing certificate is returned as part of the Signature.

Witness

The BundleBuilder may also be configured with zero-or-more Witness instances. Each Witness receives the artifact signature and the public key and returns an VerificationMaterial which represents some sort of counter-signature for the artifact's signature.

interface Witness {
  testify: (
    signature: SignatureBundle,
    publicKey: string
  ) => Promise<VerificationMaterial>;
}

The returned VerificationMaterial may contain either Rekor transparency log entries or RFC3161 timestamps.

type VerificationMaterial = {
  tlogEntries?: TransparencyLogEntry[];
  rfc3161Timestamps?: RFC3161SignedTimestamp[];
};

The entries in the returned VerificationMaterial are automatically added to the Sigstore Bundle by the BundleBuilder.

The package provides two different Witness implementations:

• RekorWitness - Adds an entry to the Rekor transparency log and returns a TransparencyLogEntry to be included in the Bundle
• TSAWitness - Requests an RFC3161 timestamp over the artifact signature and returns an RFC3161SignedTimestamp to be included in the Bundle

Usage Example

const {
  CIContextProvider,
  DSSEBundleBuilder,
  FulcioSigner,
  RekorWitness,
  TSAWitness,
} = require('@sigstore/sign');

// Set-up the signer
const signer = new FulcioSigner({
  fulcioBaseURL: 'https://fulcio.sigstore.dev',
  identityProvider: new CIContextProvider('sigstore'),
});

// Set-up the witnesses
const rekorWitness = new RekorWitness({
  rekorBaseURL: 'https://rekor.sigstore.dev',
});

const tsaWitness = new TSAWitness({
  tsaBaseURL: 'https://tsa.github.com',
});

// Instantiate a bundle builder
const bundler = new DSSEBundleBuilder({
  signer,
  witnesses: [rekorWitness, tsaWitness],
});

// Sign a thing
const artifact = {
  type: 'text/plain',
  data: Buffer.from('something to be signed'),
};
const bundle = await bundler.create(artifact);

Similar packages

Other packages similar to @sigstore/sign

openpgp

OpenPGP.js is a JavaScript implementation of the OpenPGP protocol. It provides functionalities for signing, encrypting, decrypting, and verifying messages and files. Compared to @sigstore/sign, OpenPGP.js offers a broader range of cryptographic operations but does not specifically focus on the software supply chain.

node-forge

Node-forge is a JavaScript library that provides a wide range of cryptographic functionalities, including signing and verifying data. It is a general-purpose cryptographic library and does not specifically target the software supply chain like @sigstore/sign.

jsonwebtoken

Jsonwebtoken is a library for signing and verifying JSON Web Tokens (JWT). While it focuses on JWTs rather than general software artifacts, it provides similar signing and verification functionalities. It is more specialized in handling tokens for authentication and authorization purposes.