Adding client information for sigstore-js

content/en/language_clients/javascript/_index.html

@@ -0,0 +1,11 @@
+---
+type: docs
+title: "JavaScript"
+description: "sigstore-js"
+lead: "JavaScript Language Client"
+date: 2024-10-06T08:49:15+00:00
+lastmod: 2024-10-06T08:49:15+00:00
+draft: false
+images: []
+weight: 10
+---

content/en/language_clients/javascript/bundle.md

@@ -0,0 +1,25 @@
+---
+type: docs
+category: JavaScript
+menuTitle: bundle
+title: bundle
+weight: 20
+---
+
+@sigstore/bundle is a JavaScript library for working with the Sigstore bundle format.
+
+## Features
+
+- TypeScript types for the different Sigstore bundle versions.
+- Bundle validation functions.
+- Support for serializing/deserializing bundles to/from JSON.
+
+## Prerequisites
+
+- Node.js version >= 18.17.0
+
+## Installation
+
+```
+npm install @sigstore/bundle
+```

content/en/language_clients/javascript/cli.md

@@ -0,0 +1,192 @@
+---
+type: docs
+category: JavaScript
+menuTitle: cli
+title: cli
+weight: 30
+---
+
+@sigstore/cli is a CLI for creating and verifying Sigstore bundles.
+
+# Usage
+<!-- usage -->
+```sh-session
+$ npm install -g @sigstore/cli
+$ sigstore COMMAND
+running command...
+$ sigstore (--version)
+@sigstore/cli/0.8.0 darwin-arm64 node-v22.3.0
+$ sigstore --help [COMMAND]
+USAGE
+  $ sigstore COMMAND
+...
+```
+<!-- usagestop -->
+
+# Commands
+
+<!-- commands -->
+* [`sigstore attach IMAGE-URI`](#sigstore-attach-image-uri)
+* [`sigstore attest FILE`](#sigstore-attest-file)
+* [`sigstore help [COMMAND]`](#sigstore-help-command)
+* [`sigstore initialize`](#sigstore-initialize)
+* [`sigstore verify BUNDLE`](#sigstore-verify-bundle)
+
+## `sigstore attach IMAGE-URI`
+
+attach an attestation to a container image
+
+```
+USAGE
+  $ sigstore attach IMAGE-URI --attestation <value> [-u <value> -p <value>]
+
+ARGUMENTS
+  IMAGE-URI  fully qualified URI to the image
+
+FLAGS
+  -p, --password=<value>     password for the registry
+  -u, --username=<value>     username for the registry
+      --attestation=<value>  (required) attestation bundle to attach
+
+DESCRIPTION
+  attach an attestation to a container image
+
+EXAMPLES
+  $ sigstore attach --attestation <file> <name>{:<tag>|@<digest>}
+```
+
+
+
+## `sigstore attest FILE`
+
+attest the supplied file
+
+```
+USAGE
+  $ sigstore attest FILE [--json] [--fulcio-url <value>] [--rekor-url <value>] [--tsa-server-url <value>]
+    [--tlog-upload] [--oidc-client-id <value>] [--oidc-client-secret <value>] [--oidc-issuer <value>]
+    [--oidc-redirect-url <value>] [-t <value>] [-o <value>] [--timeout <value>]
+
+ARGUMENTS
+  FILE  file to attest
+
+FLAGS
+  -o, --output-file=<value>         write output to file
+  -t, --payload-type=<value>        [default: application/vnd.in-toto+json] MIME or content type to apply to the DSSE
+                                    envelope
+      --fulcio-url=<value>          [default: https://fulcio.sigstore.dev] URL to the Sigstore PKI server
+      --oidc-client-id=<value>      [default: sigstore] OIDC client ID for application
+      --oidc-client-secret=<value>  OIDC client secret for application
+      --oidc-issuer=<value>         [default: https://oauth2.sigstore.dev/auth] OIDC provider to be used to issue ID
+                                    token
+      --oidc-redirect-url=<value>   OIDC redirect URL
+      --rekor-url=<value>           [default: https://rekor.sigstore.dev] URL to the Rekor transparency log
+      --timeout=<value>             [default: 5] timeout in seconds for API requests
+      --[no-]tlog-upload            whether or not to upload entry to the transparency log
+      --tsa-server-url=<value>      URL to the Timestamping Authority
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  attest the supplied file
+
+EXAMPLES
+  $ sigstore attest ./statement.json
+```
+
+
+
+## `sigstore help [COMMAND]`
+
+Display help for sigstore.
+
+```
+USAGE
+  $ sigstore help [COMMAND...] [-n]
+
+ARGUMENTS
+  COMMAND...  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for sigstore.
+```
+
+
+
+## `sigstore initialize`
+
+initialize the Sigstore TUF root to retrieve trusted certificates and keys for verification
+
+```
+USAGE
+  $ sigstore initialize [--mirror <value>] [--root <value>] [--cache-path <value>] [--force]
+
+FLAGS
+  --cache-path=<value>  Absolute path to the directory to be used for caching downloaded TUF metadata and targets
+  --force               force initialization even if the cache already exists
+  --mirror=<value>      [default: https://tuf-repo-cdn.sigstore.dev] URL to the Sigstore TUF repository
+  --root=<value>        path to the initial trusted root. Defaults to the embedded root.
+
+DESCRIPTION
+  initialize the Sigstore TUF root to retrieve trusted certificates and keys for verification
+
+ALIASES
+  $ sigstore init
+
+EXAMPLES
+  $ sigstore initialize
+```
+
+
+
+## `sigstore verify BUNDLE`
+
+verify the supplied .sigstore bundle file
+
+```
+USAGE
+  $ sigstore verify BUNDLE [--json] [--tlog-threshold <value>] [--ctlog-threshold <value>]
+    [--certificate-identity-email <value> --certificate-issuer <value>] [--certificate-identity-uri <value> ]
+    [--tuf-mirror-url <value>] [--tuf-root-path <value>] [--tuf-cache-path <value>] [--tuf-force-cache] [--blob-file
+    <value> | --blob <value>]
+
+ARGUMENTS
+  BUNDLE  bundle to verify
+
+FLAGS
+  --blob=<value>                        Base64 encoded data to verify. Only required if bundle was not signed using
+                                        attest
+  --blob-file=<value>                   File containing data to verify. Only required if bundle was not signed using
+                                        attest
+  --certificate-identity-email=<value>  Email address which must appear in the signing certificate's Subject Alternative
+                                        Name (SAN) extension. Not verified if no value is supplied
+  --certificate-identity-uri=<value>    URI which must appear in the signing certificate's Subject Alternative Name
+                                        (SAN) extension. Not verified if no value is supplied
+  --certificate-issuer=<value>          Value that must appear in the signing certificate's issuer extension (OID
+                                        1.3.6.1.4.1.57264.1.1 or 1.3.6.1.4.1.57264.1.8). Not verified if no value is
+                                        supplied
+  --ctlog-threshold=<value>             [default: 1] number of certificate transparency log entries required to verify
+  --tlog-threshold=<value>              [default: 1] number of transparency log entries required to verify
+  --tuf-cache-path=<value>              Absolute path to the directory to be used for caching downloaded TUF metadata
+                                        and targets
+  --tuf-force-cache                     Whether to give precedence to cached, un-expired TUF metadata and targets over
+                                        remote versions
+  --tuf-mirror-url=<value>              Base URL for the Sigstore TUF repository
+  --tuf-root-path=<value>               Path to the initial trust root for the TUF repository
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  verify the supplied .sigstore bundle file
+
+EXAMPLES
+  $ sigstore verify ./bundle.sigstore
+```
+
+
+<!-- commandsstop -->

content/en/language_clients/javascript/javascript_client_overview.md

@@ -0,0 +1,23 @@
+---
+type: docs
+category: JavaScript
+menuTitle: JavaScript Client Overview
+title: JavaScript Client Overview
+weight: 1
+---
+
+[sigstore-js](https://github.com/sigstore/sigstore-js) is a collection of javascript libraries for interacting with sigstore. 
+
+## Libraries
+
+### Global package
+
+* [`sigstore`](./packages/client) - Client library implementing Sigstore signing/verification workflows.
+
+## Scoped packages
+* [`@sigstore/bundle`](./packages/bundle) - TypeScript types and utility functions for working with Sigstore bundles.
+* [`@sigstore/cli`](./packages/cli) - Command line interface for signing/verifying artifacts with Sigstore.
+* [`@sigstore/sign`](./packages/sign) - Library for generating Sigstore signatures.
+* [`@sigstore/tuf`](./packages/tuf) - Library for interacting with the Sigstore TUF repository.
+* [`@sigstore/rekor-types`](./packages/rekor-types) - TypeScript types for the Sigstore Rekor REST API.
+* [`@sigstore/mock`](./packages/mock) - Mocking library for Sigstore services.

content/en/language_clients/javascript/mock.md

@@ -0,0 +1,85 @@
+---
+type: docs
+category: JavaScript
+menuTitle: mock
+title: mock
+weight: 70
+---
+
+@sigstore/mock builds on top of the [`nock`][1] library to set-up mock endpoints for Sigstore
+services.
+
+## Features
+
+* Mocked version of the Sigstore Fulcio `POST /api/v2/signingCert` API which
+  returns a verifiable certificate signed by an ephemeral certificate authority.
+* Mocked version of the Sigstore Rekor `POST /api/v1/log/entries` API which
+  returns a log entry with a verifiable signed-entry timestamp (SET).
+* Mocked version of the Sigstore Timestamp Authority `POST /api/v1/timestamp`
+  API which returns a verifiable signed timestamp.
+
+## To Do
+
+* Mocked TUF repository which returns the key material necessary to
+  verify artifacts returned from the other services.
+
+## Prerequisites
+
+- Node.js version >= 18.17.0
+
+## Installation
+
+```
+npm install @sigstore/mock
+```
+
+## Usage
+
+```javascript
+const { mockFulcio, mockRekor, mockTSA } = require('@sigstore/mock')
+```
+
+```javascript
+import { mockFulcio, mockRekor, mockTSA } from '@sigstore/mock'
+```
+
+### mockFulcio([options])
+Sets-up a `nock`-based mock endpoint for the Fulcio `POST /api/v2/signingCert` API.
+
+* `options` `<Object>`
+  * `baseURL` `<string>`: Base URL for mocked Fulcio API server. Defaults to
+    `'https://fulcio.sigstore.dev'`
+  * `strict` `<boolean>`: Flag indicating whether or not the request payload
+    will be parsed. When set to `true` the request must contain a well-formed
+    OIDC token and a well-formed public key. The OIDC token does NOT need to be
+    signed or contain a verifiable signature. The supplied public key will be
+    part of the returned certificate. When set to `false` the request body will
+    not be interpreted and a dummy OIDC token and key will be used to provision
+    the certificate. Defaults to `true`.
+
+### mockRekor([options])
+Sets-up a `nock`-based mock endpoint for the Rekor `POST /api/v1/log/entries` API.
+
+* `options` `<Object>`
+  * `baseURL` `<string>`: Base URL for mocked Rekor API server. Defaults to
+    `'https://rekor.sigstore.dev'`
+  * `strict` `<boolean>`: Flag indicating whether or not the request payload
+    will be parsed. When set to `true` the request must contain a well-formed
+    JSON string. The supplied JSON object will be embedded in the returned
+    log entry. When set to `false` the request body will not be interpreted
+    and a dummy proposed entry  be used. Defaults to `true`.
+
+### mockTSA([options])
+Sets-up a `nock`-based mock endpoint for the Timestamp Authority `POST /api/v1/timestamp` API.
+
+* `options` `<Object>`
+  * `baseURL` `<string>`: Base URL for mocked TSA API server. Defaults to
+    `'https://timestamp.sigstore.dev'`
+  * `strict` `<boolean>`: Flag indicating whether or not the request payload
+    will be parsed. When set to `true` the request must contain a well-formed
+    JSON string. The supplied JSON object will be used to set the artifact hash
+    and hash algorithm in the returned timestamp. When set to `false` the
+    request body will not be interpreted and a dummy artifact hash will be
+    used. Defaults to `true`.
+
+[1]: https://github.com/nock/nock

content/en/language_clients/javascript/rekor.md

@@ -0,0 +1,20 @@
+---
+type: docs
+category: JavaScript
+menuTitle: rekor-types
+title: rekor-types
+weight: 60
+---
+@sigstore/rekor-types is a library of TypeScript types for the Sigstore [Rekor][1] REST API.
+
+## Updating Rekor Types
+
+Update the git `REF` in `hack/generate-rekor-types` from the [sigstore/rekor][1] repository.
+
+Generate TypeScript types (should update files in scr/\_\_generated\_\_):
+
+```
+npm run codegen
+```
+
+[1]: https://github.com/sigstore/rekor