{"_id":"@sigstore/sign","_rev":"291842","name":"@sigstore/sign","description":"Sigstore signing library","dist-tags":{"latest":"2.1.0"},"maintainers":[{"name":"bdehamer","email":""},{"name":"mylesborins","email":""}],"time":{"modified":"2023-10-06T06:37:31.000Z","created":"2023-08-10T16:18:29.208Z","2.1.0":"2023-08-29T15:40:24.461Z","2.0.0":"2023-08-18T16:05:36.544Z","1.0.0":"2023-08-10T16:18:29.208Z"},"users":{},"author":{"name":"bdehamer@github.com"},"repository":{"type":"git","url":"git+https://github.com/sigstore/sigstore-js.git"},"versions":{"2.1.0":{"name":"@sigstore/sign","version":"2.1.0","description":"Sigstore signing library","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"clean":"shx rm -rf dist *.tsbuildinfo","build":"tsc --build","test":"jest"},"author":{"name":"bdehamer@github.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/sigstore/sigstore-js.git"},"bugs":{"url":"https://github.com/sigstore/sigstore-js/issues"},"homepage":"https://github.com/sigstore/sigstore-js/tree/main/packages/sign#readme","publishConfig":{"provenance":true},"devDependencies":{"@sigstore/jest":"^0.0.0","@sigstore/mock":"^0.4.0","@sigstore/rekor-types":"^2.0.0","@types/make-fetch-happen":"^10.0.0"},"dependencies":{"@sigstore/bundle":"^2.1.0","@sigstore/protobuf-specs":"^0.2.1","make-fetch-happen":"^13.0.0"},"engines":{"node":"^16.14.0 || >=18.0.0"},"_id":"@sigstore/sign@2.1.0","gitHead":"26d16513386ffaa790b1c32f927544f1322e4194","_nodeVersion":"16.20.2","_npmVersion":"9.8.1","dist":{"shasum":"801f4b5f60e13ecd1925117a7d084ab7b2199f01","size":21035,"noattachment":false,"key":"/@sigstore/sign/-/@sigstore/sign-2.1.0.tgz","tarball":"http://name.csiicloud.com:7001/@sigstore/sign/download/@sigstore/sign-2.1.0.tgz"},"_npmUser":{"name":"bdehamer","email":"brian@dehamer.com"},"directories":{},"maintainers":[{"name":"bdehamer","email":""},{"name":"mylesborins","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/sign_2.1.0_1693323624175_0.08146269126692629"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-08-29T15:40:24.461Z","publish_time":1693323624461,"_source_registry_name":"default","_cnpm_publish_time":1693323624461},"2.0.0":{"name":"@sigstore/sign","version":"2.0.0","description":"Sigstore signing library","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"clean":"shx rm -rf dist *.tsbuildinfo","build":"tsc --build","test":"jest"},"author":{"name":"bdehamer@github.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/sigstore/sigstore-js.git"},"bugs":{"url":"https://github.com/sigstore/sigstore-js/issues"},"homepage":"https://github.com/sigstore/sigstore-js/tree/main/packages/sign#readme","publishConfig":{"provenance":true},"devDependencies":{"@sigstore/jest":"^0.0.0","@sigstore/mock":"^0.3.0","@sigstore/rekor-types":"^2.0.0","@types/make-fetch-happen":"^10.0.0"},"dependencies":{"@sigstore/bundle":"^2.0.0","@sigstore/protobuf-specs":"^0.2.1","make-fetch-happen":"^13.0.0"},"engines":{"node":"^16.14.0 || >=18.0.0"},"_id":"@sigstore/sign@2.0.0","gitHead":"f0b49a04e5a62250e0f60fb128004a73110fe311","_nodeVersion":"16.20.2","_npmVersion":"9.8.1","dist":{"shasum":"ebd6e76227259d82e592d7651d97126c04a04e3f","size":20493,"noattachment":false,"key":"/@sigstore/sign/-/@sigstore/sign-2.0.0.tgz","tarball":"http://name.csiicloud.com:7001/@sigstore/sign/download/@sigstore/sign-2.0.0.tgz"},"_npmUser":{"name":"bdehamer","email":"brian@dehamer.com"},"directories":{},"maintainers":[{"name":"bdehamer","email":""},{"name":"mylesborins","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/sign_2.0.0_1692374736282_0.705483606246113"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-08-18T16:05:36.544Z","publish_time":1692374736544,"_source_registry_name":"default","_cnpm_publish_time":1692374736544},"1.0.0":{"name":"@sigstore/sign","version":"1.0.0","description":"Sigstore signing library","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"clean":"shx rm -rf dist *.tsbuildinfo","build":"tsc --build","test":"jest"},"author":{"name":"bdehamer@github.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/sigstore/sigstore-js.git"},"bugs":{"url":"https://github.com/sigstore/sigstore-js/issues"},"homepage":"https://github.com/sigstore/sigstore-js/tree/main/packages/sign#readme","publishConfig":{"provenance":true},"devDependencies":{"@sigstore/jest":"^0.0.0","@sigstore/mock":"^0.2.0","@sigstore/rekor-types":"^1.0.0","@types/make-fetch-happen":"^10.0.0"},"dependencies":{"@sigstore/bundle":"^1.1.0","@sigstore/protobuf-specs":"^0.2.0","make-fetch-happen":"^11.0.1"},"engines":{"node":"^14.17.0 || ^16.13.0 || >=18.0.0"},"_id":"@sigstore/sign@1.0.0","gitHead":"591db8d9680e29e96813df1d49ce44529385b433","_nodeVersion":"16.20.1","_npmVersion":"9.8.1","dist":{"shasum":"6b08ebc2f6c92aa5acb07a49784cb6738796f7b4","size":20855,"noattachment":false,"key":"/@sigstore/sign/-/@sigstore/sign-1.0.0.tgz","tarball":"http://name.csiicloud.com:7001/@sigstore/sign/download/@sigstore/sign-1.0.0.tgz"},"_npmUser":{"name":"bdehamer","email":"brian@dehamer.com"},"directories":{},"maintainers":[{"name":"bdehamer","email":""},{"name":"mylesborins","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/sign_1.0.0_1691684309032_0.26132649557242993"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-08-10T16:18:29.208Z","publish_time":1691684309208,"_source_registry_name":"default","_cnpm_publish_time":1691684309208}},"readme":"# @sigstore/sign &middot; [![npm version](https://img.shields.io/npm/v/@sigstore/sign.svg?style=flat)](https://www.npmjs.com/package/sigstore) [![CI Status](https://github.com/sigstore/sigstore-js/workflows/CI/badge.svg)](https://github.com/sigstore/sigstore-js/actions/workflows/ci.yml) [![Smoke Test Status](https://github.com/sigstore/sigstore-js/workflows/smoke-test/badge.svg)](https://github.com/sigstore/sigstore-js/actions/workflows/smoke-test.yml)\n\nA library for generating [Sigstore][1] signatures.\n\n## Features\n\n- Support for keyless signature generation with [Fulcio][2]-issued signing\n  certificates\n- Support for ambient OIDC credential detection in CI/CD environments\n- Support for recording signatures to the [Rekor][3] transparency log\n- Support for requesting timestamped countersignature from a [Timestamp\n  Authority][4]\n\n## Prerequisites\n\n- Node.js version >= 14.17.0\n\n## Installation\n\n```\nnpm install @sigstore/sign\n```\n\n## Overview\n\nThis library provides the building blocks for composing custom Sigstore signing\nworkflows.\n\n### BundleBuilder\n\nThe top-level component is the `BundleBuilder` which has responsibility for\ntaking some artifact and returning a [Sigstore bundle][5] containing the\nsignature for that artifact and the various materials necessary to verify that\nsignature.\n\n```typescript\ninterface BundleBuilder {\n  create: (artifact: Artifact) => Promise<Bundle>;\n}\n```\n\nThe artifact to be signed is simply an array of bytes and an optional mimetype.\nThe type is necessary when the signature is packaged as a [DSSE][6] envelope.\n\n```typescript\ntype Artifact = {\n  data: Buffer;\n  type?: string;\n};\n```\n\nThere are two `BundleBuilder` implementations provided as part of this package:\n\n- [`DSSEBundleBuilder`](./src/bundler/dsse.ts) - Combines the verification material and\n  artifact signature into a [`dsse_envelope`][7] -style Sigstore bundle\n- [`MessageBundleBuilder`](./src/bundler/message.ts) - Combines the verification\n  material and artifact signature into a [`message_signature`][8]-style Sigstore\n  bundle.\n\n### Signer\n\nEvery `BundleBuilder` must be instantiated with a `Signer` implementation. The\n`Signer` is responsible for taking a `Buffer` and returning an `Signature`.\n\n```typescript\ninterface Signer {\n  sign: (data: Buffer) => Promise<Signature>;\n}\n```\n\nThe returned `Signature` contains a signature and the public key which can be\nused to verify that signature -- the key may either take the form of a x509\ncertificate or public key.\n\n```typescript\ntype Signature = {\n  signature: Buffer;\n  key: KeyMaterial;\n};\n\ntype KeyMaterial =\n  | {\n      $case: 'x509Certificate';\n      certificate: string;\n    }\n  | {\n      $case: 'publicKey';\n      publicKey: string;\n      hint?: string;\n    };\n```\n\nThis package provides the [`FulcioSigner`](./src/signer/fulcio/index.ts)\nwhich implements the `Signer` interface and signs the artifact with an\nephemeral keypair. It will also retrieve an OIDC token from the configured\n`IdentityProvider` and then request a signing certificate from Fulcio which binds\nthe ephemeral key to the identity embedded in the token. This signing\ncertificate is returned as part of the `Signature`.\n\n### Witness\n\nThe `BundleBuilder` may also be configured with zero-or-more `Witness`\ninstances. Each `Witness` receives the artifact signature and the public key\nand returns an `VerificationMaterial` which represents some sort of\ncounter-signature for the artifact's signature.\n\n```typescript\ninterface Witness {\n  testify: (\n    signature: SignatureBundle,\n    publicKey: string\n  ) => Promise<VerificationMaterial>;\n}\n```\n\nThe returned `VerificationMaterial` may contain either Rekor transparency log\nentries or RFC3161 timestamps.\n\n```typescript\ntype VerificationMaterial = {\n  tlogEntries?: TransparencyLogEntry[];\n  rfc3161Timestamps?: RFC3161SignedTimestamp[];\n};\n```\n\nThe entries in the returned `VerificationMaterial` are automatically added to\nthe Sigstore `Bundle` by the `BundleBuilder`.\n\nThe package provides two different `Witness` implementations:\n\n- [`RekorWitness`](./src/witness/tlog/index.ts) - Adds an entry to the Rekor\n  transparency log and returns a `TransparencyLogEntry` to be included in the\n  `Bundle`\n- [`TSAWitness`](./src/witness/tsa/index.ts) - Requests an RFC3161 timestamp\n  over the artifact signature and returns an `RFC3161SignedTimestamp` to be\n  included in the `Bundle`\n\n## Usage Example\n\n```typescript\nconst {\n  CIContextProvider,\n  DSSEBundleBuilder,\n  FulcioSigner,\n  RekorWitness,\n  TSAWitness,\n} = require('@sigstore/sign');\n\n// Set-up the signer\nconst signer = new FulcioSigner({\n  fulcioBaseURL: 'https://fulcio.sigstore.dev',\n  identityProvider: new CIContextProvider('sigstore'),\n});\n\n// Set-up the witnesses\nconst rekorWitness = new RekorWitness({\n  rekorBaseURL: 'https://rekor.sigstore.dev',\n});\n\nconst tsaWitness = new TSAWitness({\n  tsaBaseURL: 'https://tsa.github.com',\n});\n\n// Instantiate a bundle builder\nconst bundler = new DSSEBundleBuilder({\n  signer,\n  witnesses: [rekorWitness, tsaWitness],\n});\n\n// Sign a thing\nconst artifact = {\n  data: Buffer.from('something to be signed'),\n};\nconst bundle = await bundler.create(artifact);\n```\n\n[1]: https://www.sigstore.dev\n[2]: https://github.com/sigstore/fulcio\n[3]: https://github.com/sigstore/rekor\n[4]: https://github.com/sigstore/timestamp-authority\n[5]: https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto\n[6]: https://github.com/secure-systems-lab/dsse\n[7]: https://github.com/sigstore/protobuf-specs/blob/5ef54068bb534152474c5685f5cd248f38549fbd/protos/sigstore_bundle.proto#L80\n[8]: https://github.com/sigstore/protobuf-specs/blob/5ef54068bb534152474c5685f5cd248f38549fbd/protos/sigstore_bundle.proto#L74\n","_attachments":{},"homepage":"https://github.com/sigstore/sigstore-js/tree/main/packages/sign#readme","bugs":{"url":"https://github.com/sigstore/sigstore-js/issues"},"license":"Apache-2.0"}