README.md
1# sigstore · [](https://www.npmjs.com/package/sigstore) [](https://github.com/sigstore/sigstore-js/actions/workflows/ci.yml) [](https://github.com/sigstore/sigstore-js/actions/workflows/smoke-test.yml)
2
3A JavaScript library for generating and verifying Sigstore signatures. One of
4the intended uses is to sign and verify npm packages but it can be used to sign
5and verify any file.
6
7## Features
8
9* Support for signing using an OpenID Connect identity
10* Support for publishing signatures to a [Rekor][1] instance
11* Support for verifying Sigstore bundles
12
13## Prerequisites
14
15- Node.js version >= 14.17.0
16
17## Installation
18
19```
20npm install sigstore
21```
22
23## Usage
24
25```javascript
26const { sigstore } = require('sigstore')
27```
28
29```javascript
30import { sigstore } from 'sigstore'
31```
32
33### sign(payload[, options])
34
35Generates a Sigstore signature for the supplied payload. Returns a
36[Sigstore bundle][2] containing the signature and the verification material
37necessary to verify the signature.
38
39* `payload` `<Buffer>`: The bytes of the artifact to be signed.
40* `options` `<Object>`
41 * `fulcioURL` `<string>`: The base URL of the Fulcio instance to use for retrieving the signing certificate. Defaults to `'https://fulcio.sigstore.dev'`.
42 * `rekorURL` `<string>`: The base URL of the Rekor instance to use when adding the signature to the transparency log. Defaults to `'https://rekor.sigstore.dev'`.
43 * `tsaServerURL` `<string>`: The base URL of the Timestamp Authority instance to use when requesting a signed timestamp. If omitted, no timestamp will be requested.
44 * `tlogUpload` `<boolean>`: Flag indicating whether or not the signature should be recorded on the Rekor transparency log. Defaults to `true`.
45 * `identityToken` `<string>`: The OIDC token identifying the signer. If no explicit token is supplied, an attempt will be made to retrieve one from the environment. This config cannot be used with `identityProvider`.
46 * `identityProvider` `<IdentityProvider>`: Object which implements `getToken: () => Promise<string>`. The supplied provider will be used to retrieve an OIDC token. If no provider is supplied, an attempt will be made to retrieve an OIDC token from the environment. This config cannot be used with `identityToken`.
47
48### attest(payload, payloadType[, options])
49
50Generates a Sigstore signature for the supplied in-toto statement. Returns a
51[Sigstore bundle][2] containing the [DSSE][3]-wrapped statement and signature
52as well as the verification material necessary to verify the signature.
53
54* `payload` `<Buffer>`: The bytes of the statement to be signed.
55* `payloadType` `<string>`: MIME or content type describing the statement to be signed.
56* `options` `<Object>`
57 * `fulcioURL` `<string>`: The base URL of the Fulcio instance to use for retrieving the signing certificate. Defaults to `'https://fulcio.sigstore.dev'`.
58 * `rekorURL` `<string>`: The base URL of the Rekor instance to use when adding the signature to the transparency log. Defaults to `'https://rekor.sigstore.dev'`.
59 * `tsaServerURL` `<string>`: The base URL of the Timestamp Authority instance to use when requesting a signed timestamp. If omitted, no timestamp will be requested.
60 * `tlogUpload` `<boolean>`: Flag indicating whether or not the signed statement should be recorded on the Rekor transparency log. Defaults to `true`.
61 * `identityToken` `<string>`: The OIDC token identifying the signer. If no explicit token is supplied, an attempt will be made to retrieve one from the environment. This config cannot be used with `identityProvider`.
62 * `identityProvider` `<IdentityProvider>`: Object which implements `getToken: () => Promise<string>`. The supplied provider will be used to retrieve an OIDC token. If no provider is supplied, an attempt will be made to retrieve an OIDC token from the environment. This config cannot be used with `identityToken`.
63
64
65### verify(bundle[, payload][, options])
66
67Verifies the signature in the supplied bundle.
68
69* `bundle` `<Bundle>`: The Sigstore bundle containing the signature to be verified and the verification material necessary to verify the signature.
70* `payload` `<Buffer>`: The bytes of the artifact over which the signature was created. Only necessary when the `sign` function was used to generate the signature since the Bundle does not contain any information about the artifact which was signed. Not required when the `attest` function was used to generate the Bundle.
71* `options` `<Object>`
72 * `ctLogThreshold` `<number>`: The number of certificate transparency logs on which the signing certificate must appear. Defaults to `1`.
73 * `tlogThreshold` `<number>`: The number of transparency logs on which the signature must appear. Defaults to `1`.
74 * `certificateIssuer` `<string>`: Value that must appear in the signing certificate's issuer extension (OID 1.3.6.1.4.1.57264.1.1). Not verified if no value is supplied.
75 * `certificateIdentityEmail` `<string>`: Email address which must appear in the signing certificate's Subject Alternative Name (SAN) extension. Must be specified in conjunction with the `certificateIssuer` option. Takes precedence over the `certificateIdentityURI` option. Not verified if no value is supplied.
76 * `certificateIdentityURI` `<string>`: URI which must appear in the signing certificate's Subject Alternative Name (SAN) extension. Must be specified in conjunction with the `certificateIssuer` option. Ignored if the `certificateIdentityEmail` option is set. Not verified if no value is supplied.
77 * `certificateOIDs` `<Object>`: A collection of OID/value pairs which must be present in the certificate's extension list. Not verified if no value is supplied.
78 * `keySelector` `<Function>`: Callback invoked to retrieve the public key (as either `string` or `Buffer`) necessary to verify the bundle signature. Not used when the signature was generated from a Fulcio-issued signing certificate.
79 * `hint` `<String>`: The hint from the bundle used to identify the the signing key.
80
81### tuf
82
83The `tuf` object contains utility function for working with the Sigstore TUF repository.
84
85#### client([options])
86
87Returns a TUF client which can be used to retrieve targets from the Sigstore TUF repository.
88
89* `options` `<Object>`
90 * `tufMirrorURL` `<string>`: Base URL for the Sigstore TUF repository. Defaults to `'https://tuf-repo-cdn.sigstore.dev'`
91 * `tufRootPath` `<string>`: Path to the initial trusted root for the TUF repository. Defaults to the embedded root.
92 * `tufCachePath` `<string>`: Absolute path to the directory to be used for caching downloaded TUF metadata and targets. Defaults to a directory named "sigstore-js" within the platform-specific application data directory.
93
94The returned object exposes a `getTarget(path)` function which returns the
95contents of the target at the specified path in the Sigstore TUF repository.
96
97#### getTarget(path[, options]) (deprecated)
98
99Returns the contents of the target at the specified path in the Sigstore TUF repository.
100This method has been deprecated and will be removed in the next major version.
101You should use the TUF `client` function to retrieve a stateful TUF client and
102then call `getTarget` against that object. This will avoid re-initializing the
103internal TUF state between requests.
104
105* `path` `<string>`: The [path-relative-url string](https://url.spec.whatwg.org/#path-relative-url-string) that uniquely identifies the target within the Sigstore TUF repository.
106* `options` `<Object>`
107 * `tufMirrorURL` `<string>`: Base URL for the Sigstore TUF repository. Defaults to `'https://tuf-repo-cdn.sigstore.dev'`
108 * `tufRootPath` `<string>`: Path to the initial trusted root for the TUF repository. Defaults to the embedded root.
109 * `tufCachePath` `<string>`: Absolute path to the directory to be used for caching downloaded TUF metadata and targets. Defaults to a directory named "sigstore-js" within the platform-specific application data directory.
110
111
112### utils
113
114The `utils` object contains a few internal utility functions. These are exposed
115to support the needs of specific `sigstore-js` consumers but should **NOT** be
116considered part of the stable public interface.
117
118## CLI
119
120The `sigstore-js` library comes packaged with a basic command line interface
121for testing and demo purposes. However, the CLI should **NOT** be considered
122part of the stable interface of the library. If you require a production-ready
123Sigstore CLI, we recommend you use [`cosign`][4].
124
125```shell
126$ npx sigstore help
127sigstore <command> <artifact>
128
129 Usage:
130
131 sigstore sign sign an artifact
132 sigstore attest sign an artifact using dsse (Dead Simple Signing Envelope)
133 sigstore verify verify an artifact
134 sigstore version print version information
135 sigstore help print help information
136```
137
138## Credential Sources
139
140### GitHub Actions
141
142If sigstore-js detects that it is being executed on GitHub Actions, it will use `ACTIONS_ID_TOKEN_REQUEST_URL`
143and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` environment variables to request an OIDC token with the correct scope.
144
145Note: the `id_token: write` permission must be granted to the GitHub Action Job.
146
147See https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
148for more details.
149
150### Environment Variables
151
152If the `SIGSTORE_ID_TOKEN` environment variable is set, it will use this to authenticate to Fulcio.
153It is the callers responsibility to make sure that this token has the correct scopes.
154
155### Interactive Flow
156
157If sigstore-js cannot detect ambient credentials, then it will prompt the user to go through the
158interactive flow.
159
160
161
162[1]: https://github.com/sigstore/rekor
163[2]: https://github.com/sigstore/protobuf-specs/blob/9b722b68a717778ba4f11543afa4ef93205ab502/protos/sigstore_bundle.proto#L63-L84
164[3]: https://github.com/secure-systems-lab/dsse
165[4]: https://github.com/sigstore/cosign
166
){kind=link}
){kind=link}
){kind=link}