From c209d860adf4c9c554a81a06a2002e337d0f4186 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sun, 3 Nov 2024 12:57:17 -0800 Subject: [PATCH 1/6] Adding info for JS client. Signed-off-by: hayleycd --- .../language_clients/javascript/_index.html | 11 +++ .../language_clients/javascript/overview.md | 70 +++++++++++++++++++ .../language_client_overview.md | 5 +- 3 files changed, 84 insertions(+), 2 deletions(-) create mode 100644 content/en/language_clients/javascript/_index.html create mode 100644 content/en/language_clients/javascript/overview.md diff --git a/content/en/language_clients/javascript/_index.html b/content/en/language_clients/javascript/_index.html new file mode 100644 index 00000000..c98b0190 --- /dev/null +++ b/content/en/language_clients/javascript/_index.html @@ -0,0 +1,11 @@ +--- +type: docs +title: "JavaScript" +description: "JavaScript Language Client" +lead: "JavaScript Language Client" +date: 2024-10-06T08:49:15+00:00 +lastmod: 2024-10-06T08:49:15+00:00 +draft: false +images: [] +weight: 40 +--- \ No newline at end of file diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md new file mode 100644 index 00000000..b51eb250 --- /dev/null +++ b/content/en/language_clients/javascript/overview.md @@ -0,0 +1,70 @@ +--- +type: docs +category: JavaScript +title: JavaScript Client Overview +weight: 5 +--- + +[sigstore-js](https://github.com/sigstore/sigstore-js) is a collection of [javascript libraries](#additional-packages) for interacting with Sigstore. + +The main package,[`sigstore`](https://www.npmjs.com/package/sigstore), is a JavaScript library for generating and verifying Sigstore signatures. One of the intended uses is to sign and verify npm packages but it can be used to sign and verify any file. + +Full project documentation can be found in the [sigstore-js](https://github.com/sigstore/sigstore-js#sigstore-js---) project README and in each [package README](https://github.com/sigstore/sigstore-js/tree/main/packages). + +## Features + +- Support for signing using an OpenID Connect identity +- Support for publishing signatures to a [Rekor](../../logging/overview/) instance +- Support for verifying Sigstore bundles + +## Installation + +[`sigstore`](https://www.npmjs.com/package/sigstore) requires Node.js version >= 18.17.0. + +To install `sigstore` run the following command: + +```console +npm install sigstore +``` + +## Example + To use `sigstore`, import the following into your project using the following: + + ```console + const { sign, verify } = require('sigstore'); + ``` + + ```console + import { sign, verify } from 'sigstore'; + ``` + + ### Sign + + The following function will sign the file `foo.txt`: + + ```console + sign('foo.txt'); + ``` + + There are a number of optional arguments that can be used with the sign function. Additional information is available in the [project repository](https://github.com/sigstore/sigstore-js/tree/main/packages/client#signpayload-options). + + The sign function will return a Sigstore bundle (`foo.txt.sigstore.json`) which includes the signature and the necessary verification material. + +### Verify + +The following function will verify the file `foo.txt`: + +```console +verify('foo.txt.sigstore.json', payload='foo.txt', certificateIssuer='odicIssuerURL', certificateIdentityEmail='myEmail@example.com' ) +``` + +## Additional Packages + +The [sigstore-js](https://github.com/sigstore/sigstore-js) project includes additional functionality through its scoped packages. + +- [`@sigstore/bundle`](https://www.npmjs.com/package/@sigstore/bundle) - TypeScript types and utility functions for working with Sigstore bundles. +- [`@sigstore/cli`](https://www.npmjs.com/package/@sigstore/cli) - Command line interface for signing/verifying artifacts with Sigstore. +- [`@sigstore/sign`](https://www.npmjs.com/package/@sigstore/sign) - Library for generating Sigstore signatures. +- [`@sigstore/tuf`](https://www.npmjs.com/package/@sigstore/tuf) - Library for interacting with the Sigstore TUF repository. +- [`@sigstore/rekor-types`](https://www.npmjs.com/package/@sigstore/rekor-types) - TypeScript types for the Sigstore Rekor REST API. +- [`@sigstore/mock`](https://www.npmjs.com/package/@sigstore/mock) - Mocking library for Sigstore services. \ No newline at end of file diff --git a/content/en/language_clients/language_client_overview.md b/content/en/language_clients/language_client_overview.md index a974704f..a112ffe2 100644 --- a/content/en/language_clients/language_client_overview.md +++ b/content/en/language_clients/language_client_overview.md @@ -9,11 +9,12 @@ Sigstore uses [cosign](../../cosign/signing/overview) to sign and verify package Sigstore has clients for the following language ecosystems: +- [Go](https://github.com/sigstore/sigstore-go#sigstore-go) +- [Java](https://github.com/sigstore/sigstore-java#sigstore-java) +- [JavaScript](../javascript/overview) - [Python](../python/overview) - [Rust](https://github.com/sigstore/sigstore-rs#features) - [Ruby](https://github.com/sigstore/sigstore-ruby#sigstore) -- [JavaScript](https://github.com/sigstore/sigstore-js#sigstore-js---) - [Java](https://github.com/sigstore/sigstore-java#sigstore-java) -- [Go](https://github.com/sigstore/sigstore-go#sigstore-go) Language client documentation is hosted in the individual project repositories. Project summaries are currently being added to the main Sigstore documentation. From 67298c2709a523c580dde9a05712f334d3ba6f10 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sun, 3 Nov 2024 13:02:53 -0800 Subject: [PATCH 2/6] Addressing linter comments. Signed-off-by: hayleycd --- content/en/language_clients/javascript/overview.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md index b51eb250..5c927568 100644 --- a/content/en/language_clients/javascript/overview.md +++ b/content/en/language_clients/javascript/overview.md @@ -5,7 +5,7 @@ title: JavaScript Client Overview weight: 5 --- -[sigstore-js](https://github.com/sigstore/sigstore-js) is a collection of [javascript libraries](#additional-packages) for interacting with Sigstore. +[sigstore-js](https://github.com/sigstore/sigstore-js) is a collection of [javascript libraries](#additional-packages) for interacting with Sigstore. The main package,[`sigstore`](https://www.npmjs.com/package/sigstore), is a JavaScript library for generating and verifying Sigstore signatures. One of the intended uses is to sign and verify npm packages but it can be used to sign and verify any file. @@ -19,7 +19,7 @@ Full project documentation can be found in the [sigstore-js](https://github.com/ ## Installation -[`sigstore`](https://www.npmjs.com/package/sigstore) requires Node.js version >= 18.17.0. +[`sigstore`](https://www.npmjs.com/package/sigstore) requires Node.js version >= 18.17.0. To install `sigstore` run the following command: @@ -28,6 +28,7 @@ npm install sigstore ``` ## Example + To use `sigstore`, import the following into your project using the following: ```console @@ -38,7 +39,7 @@ npm install sigstore import { sign, verify } from 'sigstore'; ``` - ### Sign +### Sign The following function will sign the file `foo.txt`: @@ -48,7 +49,7 @@ npm install sigstore There are a number of optional arguments that can be used with the sign function. Additional information is available in the [project repository](https://github.com/sigstore/sigstore-js/tree/main/packages/client#signpayload-options). - The sign function will return a Sigstore bundle (`foo.txt.sigstore.json`) which includes the signature and the necessary verification material. + The sign function will return a Sigstore bundle (`foo.txt.sigstore.json`) which includes the signature and the necessary verification material. ### Verify @@ -60,11 +61,11 @@ verify('foo.txt.sigstore.json', payload='foo.txt', certificateIssuer='odicIssuer ## Additional Packages -The [sigstore-js](https://github.com/sigstore/sigstore-js) project includes additional functionality through its scoped packages. +The [sigstore-js](https://github.com/sigstore/sigstore-js) project includes additional functionality through its scoped packages. - [`@sigstore/bundle`](https://www.npmjs.com/package/@sigstore/bundle) - TypeScript types and utility functions for working with Sigstore bundles. - [`@sigstore/cli`](https://www.npmjs.com/package/@sigstore/cli) - Command line interface for signing/verifying artifacts with Sigstore. - [`@sigstore/sign`](https://www.npmjs.com/package/@sigstore/sign) - Library for generating Sigstore signatures. - [`@sigstore/tuf`](https://www.npmjs.com/package/@sigstore/tuf) - Library for interacting with the Sigstore TUF repository. - [`@sigstore/rekor-types`](https://www.npmjs.com/package/@sigstore/rekor-types) - TypeScript types for the Sigstore Rekor REST API. -- [`@sigstore/mock`](https://www.npmjs.com/package/@sigstore/mock) - Mocking library for Sigstore services. \ No newline at end of file +- [`@sigstore/mock`](https://www.npmjs.com/package/@sigstore/mock) - Mocking library for Sigstore services. From a64a000bbee80a5c3f4fa3cc8eeada24af2ade46 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sun, 3 Nov 2024 13:04:36 -0800 Subject: [PATCH 3/6] Addressing linter comments. Signed-off-by: hayleycd --- content/en/language_clients/javascript/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md index 5c927568..4683c80a 100644 --- a/content/en/language_clients/javascript/overview.md +++ b/content/en/language_clients/javascript/overview.md @@ -28,7 +28,7 @@ npm install sigstore ``` ## Example - + To use `sigstore`, import the following into your project using the following: ```console From 7b2742ef58ea3f885c952994292d6a1844e9ff61 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sun, 3 Nov 2024 13:08:19 -0800 Subject: [PATCH 4/6] Adding link to further information. Signed-off-by: hayleycd --- content/en/language_clients/javascript/overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md index 4683c80a..c36f57ef 100644 --- a/content/en/language_clients/javascript/overview.md +++ b/content/en/language_clients/javascript/overview.md @@ -59,6 +59,8 @@ The following function will verify the file `foo.txt`: verify('foo.txt.sigstore.json', payload='foo.txt', certificateIssuer='odicIssuerURL', certificateIdentityEmail='myEmail@example.com' ) ``` +More information on optional arguments can be found in the [project documentation](https://github.com/sigstore/sigstore-js/tree/main/packages/client#verifybundle-payload-options) + ## Additional Packages The [sigstore-js](https://github.com/sigstore/sigstore-js) project includes additional functionality through its scoped packages. From e959696276ba38a917cad7bcfb90cd876bad615e Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sun, 3 Nov 2024 14:02:26 -0800 Subject: [PATCH 5/6] bringing titles in line with the python pr. Signed-off-by: hayleycd --- content/en/language_clients/javascript/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md index c36f57ef..cb762be5 100644 --- a/content/en/language_clients/javascript/overview.md +++ b/content/en/language_clients/javascript/overview.md @@ -39,7 +39,7 @@ npm install sigstore import { sign, verify } from 'sigstore'; ``` -### Sign +### Signing example The following function will sign the file `foo.txt`: @@ -51,7 +51,7 @@ npm install sigstore The sign function will return a Sigstore bundle (`foo.txt.sigstore.json`) which includes the signature and the necessary verification material. -### Verify +### Verifying example The following function will verify the file `foo.txt`: From 97f80e2bddb48d51fb0c2bfe58063d0d97b91338 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Tue, 5 Nov 2024 20:39:04 -0800 Subject: [PATCH 6/6] Addressing comments. Signed-off-by: hayleycd --- content/en/language_clients/javascript/overview.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/en/language_clients/javascript/overview.md b/content/en/language_clients/javascript/overview.md index cb762be5..1e8c2ec7 100644 --- a/content/en/language_clients/javascript/overview.md +++ b/content/en/language_clients/javascript/overview.md @@ -41,22 +41,20 @@ npm install sigstore ### Signing example - The following function will sign the file `foo.txt`: - ```console - sign('foo.txt'); - ``` + const bundle = await sign(Buffer.from('hello world')); +``` There are a number of optional arguments that can be used with the sign function. Additional information is available in the [project repository](https://github.com/sigstore/sigstore-js/tree/main/packages/client#signpayload-options). - The sign function will return a Sigstore bundle (`foo.txt.sigstore.json`) which includes the signature and the necessary verification material. + The sign function will return a JSON-encoded Sigstore bundle which includes the signature and the necessary verification material. ### Verifying example -The following function will verify the file `foo.txt`: +The following function will verify the previously signed message: ```console -verify('foo.txt.sigstore.json', payload='foo.txt', certificateIssuer='odicIssuerURL', certificateIdentityEmail='myEmail@example.com' ) +verify(bundle, Buffer.from('hello world'), { certificateIssuer: 'https://token.actions.githubusercontent.com/' }); ``` More information on optional arguments can be found in the [project documentation](https://github.com/sigstore/sigstore-js/tree/main/packages/client#verifybundle-payload-options)