@actions/attest 1.0.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright 2024 GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# `@actions/attest`
+
+Functions for generating signed attestations for workflow artifacts.
+
+Attestations bind some subject (a named artifact along with its digest) to a
+predicate (some assertion about that subject) using the [in-toto
+statement](https://github.com/in-toto/attestation/tree/main/spec/v1) format. A
+signature is generated for the attestation using a
+[Sigstore](https://www.sigstore.dev/)-issued signing certificate.
+
+Once the attestation has been created and signed, it will be uploaded to the GH
+attestations API and associated with the repository from which the workflow was
+initiated.
+
+## Usage
+
+### `attest`
+
+The `attest` function takes the supplied subject/predicate pair and generates a
+signed attestation.
+
+```js
+const { attest } = require('@actions/attest');
+const core = require('@actions/core');
+
+async function run() {
+    // In order to persist attestations to the repo, this should be a token with
+    // repository write permissions.
+    const ghToken = core.getInput('gh-token');
+
+    const attestation = await attest({
+        subjectName: 'my-artifact-name',
+        subjectDigest: { 'sha256': '36ab4667...'},
+        predicateType: 'https://in-toto.io/attestation/release',
+        predicate: { . . . },
+        token: ghToken
+    });
+
+    console.log(attestation);
+}
+
+run();
+```
+
+The `attest` function supports the following options:
+
+```typescript
+export type AttestOptions = {
+  // The name of the subject to be attested.
+  subjectName: string
+  // The digest of the subject to be attested. Should be a map of digest
+  // algorithms to their hex-encoded values.
+  subjectDigest: Record<string, string>
+  // URI identifying the content type of the predicate being attested.
+  predicateType: string
+  // Predicate to be attested.
+  predicate: object
+  // GitHub token for writing attestations.
+  token: string
+  // Sigstore instance to use for signing. Must be one of "public-good" or
+  // "github".
+  sigstore?: 'public-good' | 'github'
+  // Whether to skip writing the attestation to the GH attestations API.
+  skipWrite?: boolean
+}
+```
+
+### `attestProvenance`
+
+The `attestProvenance` function accepts the name and digest of some artifact and
+generates a build provenance attestation over those values.
+
+The attestation is formed by first generating a [SLSA provenance
+predicate](https://slsa.dev/spec/v1.0/provenance) populated with
+[metadata](https://github.com/slsa-framework/github-actions-buildtypes/tree/main/workflow/v1)
+pulled from the GitHub Actions run.
+
+```js
+const { attestProvenance } = require('@actions/attest');
+const core = require('@actions/core');
+
+async function run() {
+    // In order to persist attestations to the repo, this should be a token with
+    // repository write permissions.
+    const ghToken = core.getInput('gh-token');
+
+    const attestation = await attestProvenance({
+        subjectName: 'my-artifact-name',
+        subjectDigest: { 'sha256': '36ab4667...'},
+        token: ghToken
+    });
+
+    console.log(attestation);
+}
+
+run();
+```
+
+The `attestProvenance` function supports the following options:
+
+```typescript
+export type AttestProvenanceOptions = {
+  // The name of the subject to be attested.
+  subjectName: string
+  // The digest of the subject to be attested. Should be a map of digest
+  // algorithms to their hex-encoded values.
+  subjectDigest: Record<string, string>
+  // GitHub token for writing attestations.
+  token: string
+  // Sigstore instance to use for signing. Must be one of "public-good" or
+  // "github".
+  sigstore?: 'public-good' | 'github'
+  // Whether to skip writing the attestation to the GH attestations API.
+  skipWrite?: boolean
+}
+```
+
+### `Attestation`
+
+The `Attestation` returned by `attest`/`attestProvenance` has the following
+fields:
+
+```typescript
+export type Attestation = {
+  /*
+   * JSON-serialized Sigstore bundle containing the provenance attestation,
+   * signature, signing certificate and witnessed timestamp.
+   */
+  bundle: SerializedBundle
+  /*
+   * PEM-encoded signing certificate used to sign the attestation.
+   */
+  certificate: string
+  /*
+   * ID of Rekor transparency log entry created for the attestation (if
+   * applicable).
+   */
+  tlogID?: string
+  /*
+   * ID of the persisted attestation (accessible via the GH API).
+   */
+  attestationID?: string
+}
+```
+
+For details about the Sigstore bundle format, see the [Bundle protobuf
+specification](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto).
+
+## Sigstore Instance
+
+When generating the signed attestation there are two different Sigstore
+instances which can be used to issue the signing certificate. By default,
+workflows initiated from public repositories will use the Sigstore public-good
+instance and persist the attestation signature to the public [Rekor transparency
+log](https://docs.sigstore.dev/logging/overview/). Workflows initiated from
+private/internal repositories will use the GitHub-internal Sigstore instance
+which uses a signed timestamp issued by GitHub's timestamp authority in place of
+the public transparency log.
+
+The default Sigstore instance selection can be overridden by passing an explicit
+value of either "public-good" or "github" for the `sigstore` option when calling
+either `attest` or `attestProvenance`.
+
+## Storage
+
+Attestations created by `attest`/`attestProvenance` will be uploaded to the GH
+attestations API and associated with the appropriate repository. Attestation
+storage is only supported for public repositories or repositories which belong
+to a GitHub Enterprise Cloud account.
+
+In order to generate attestations for private, non-Enterprise repositories, the
+`skipWrite` option should be set to `true`.

package/lib/attest.d.ts

@@ -0,0 +1,22 @@
+import { SigstoreInstance } from './endpoints';
+import type { Attestation } from './shared.types';
+/**
+ * Options for attesting a subject / predicate.
+ */
+export type AttestOptions = {
+    subjectName: string;
+    subjectDigest: Record<string, string>;
+    predicateType: string;
+    predicate: object;
+    token: string;
+    sigstore?: SigstoreInstance;
+    skipWrite?: boolean;
+};
+/**
+ * Generates an attestation for the given subject and predicate. The subject and
+ * predicate are combined into an in-toto statement, which is then signed using
+ * the identified Sigstore instance and stored as an attestation.
+ * @param options - The options for attestation.
+ * @returns A promise that resolves to the attestation.
+ */
+export declare function attest(options: AttestOptions): Promise<Attestation>;

package/lib/attest.js

@@ -0,0 +1,79 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attest = void 0;
+const bundle_1 = require("@sigstore/bundle");
+const crypto_1 = require("crypto");
+const endpoints_1 = require("./endpoints");
+const intoto_1 = require("./intoto");
+const sign_1 = require("./sign");
+const store_1 = require("./store");
+const INTOTO_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+/**
+ * Generates an attestation for the given subject and predicate. The subject and
+ * predicate are combined into an in-toto statement, which is then signed using
+ * the identified Sigstore instance and stored as an attestation.
+ * @param options - The options for attestation.
+ * @returns A promise that resolves to the attestation.
+ */
+function attest(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const subject = {
+            name: options.subjectName,
+            digest: options.subjectDigest
+        };
+        const predicate = {
+            type: options.predicateType,
+            params: options.predicate
+        };
+        const statement = (0, intoto_1.buildIntotoStatement)(subject, predicate);
+        // Sign the provenance statement
+        const payload = {
+            body: Buffer.from(JSON.stringify(statement)),
+            type: INTOTO_PAYLOAD_TYPE
+        };
+        const endpoints = (0, endpoints_1.signingEndpoints)(options.sigstore);
+        const bundle = yield (0, sign_1.signPayload)(payload, endpoints);
+        // Store the attestation
+        let attestationID;
+        if (options.skipWrite !== true) {
+            attestationID = yield (0, store_1.writeAttestation)((0, bundle_1.bundleToJSON)(bundle), options.token);
+        }
+        return toAttestation(bundle, attestationID);
+    });
+}
+exports.attest = attest;
+function toAttestation(bundle, attestationID) {
+    let certBytes;
+    switch (bundle.verificationMaterial.content.$case) {
+        case 'x509CertificateChain':
+            certBytes =
+                bundle.verificationMaterial.content.x509CertificateChain.certificates[0]
+                    .rawBytes;
+            break;
+        case 'certificate':
+            certBytes = bundle.verificationMaterial.content.certificate.rawBytes;
+            break;
+        default:
+            throw new Error('Bundle must contain an x509 certificate');
+    }
+    const signingCert = new crypto_1.X509Certificate(certBytes);
+    // Collect transparency log ID if available
+    const tlogEntries = bundle.verificationMaterial.tlogEntries;
+    const tlogID = tlogEntries.length > 0 ? tlogEntries[0].logIndex : undefined;
+    return {
+        bundle: (0, bundle_1.bundleToJSON)(bundle),
+        certificate: signingCert.toString(),
+        tlogID,
+        attestationID
+    };
+}
+//# sourceMappingURL=attest.js.map

package/lib/attest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attest.js","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAAqD;AACrD,mCAAsC;AACtC,2CAA8D;AAC9D,qCAA6C;AAC7C,iCAA2C;AAC3C,mCAAwC;AAIxC,MAAM,mBAAmB,GAAG,8BAA8B,CAAA;AAwB1D;;;;;;GAMG;AACH,SAAsB,MAAM,CAAC,OAAsB;;QACjD,MAAM,OAAO,GAAY;YACvB,IAAI,EAAE,OAAO,CAAC,WAAW;YACzB,MAAM,EAAE,OAAO,CAAC,aAAa;SAC9B,CAAA;QACD,MAAM,SAAS,GAAc;YAC3B,IAAI,EAAE,OAAO,CAAC,aAAa;YAC3B,MAAM,EAAE,OAAO,CAAC,SAAS;SAC1B,CAAA;QACD,MAAM,SAAS,GAAG,IAAA,6BAAoB,EAAC,OAAO,EAAE,SAAS,CAAC,CAAA;QAE1D,gCAAgC;QAChC,MAAM,OAAO,GAAY;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC5C,IAAI,EAAE,mBAAmB;SAC1B,CAAA;QACD,MAAM,SAAS,GAAG,IAAA,4BAAgB,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,MAAM,IAAA,kBAAW,EAAC,OAAO,EAAE,SAAS,CAAC,CAAA;QAEpD,wBAAwB;QACxB,IAAI,aAAiC,CAAA;QACrC,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE;YAC9B,aAAa,GAAG,MAAM,IAAA,wBAAgB,EAAC,IAAA,qBAAY,EAAC,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;SAC5E;QAED,OAAO,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC7C,CAAC;CAAA;AA1BD,wBA0BC;AAED,SAAS,aAAa,CAAC,MAAc,EAAE,aAAsB;IAC3D,IAAI,SAAiB,CAAA;IACrB,QAAQ,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,KAAK,EAAE;QACjD,KAAK,sBAAsB;YACzB,SAAS;gBACP,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC;qBACrE,QAAQ,CAAA;YACb,MAAK;QACP,KAAK,aAAa;YAChB,SAAS,GAAG,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAA;YACpE,MAAK;QACP;YACE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;KAC7D;IAED,MAAM,WAAW,GAAG,IAAI,wBAAe,CAAC,SAAS,CAAC,CAAA;IAElD,2CAA2C;IAC3C,MAAM,WAAW,GAAG,MAAM,CAAC,oBAAoB,CAAC,WAAW,CAAA;IAC3D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;IAE3E,OAAO;QACL,MAAM,EAAE,IAAA,qBAAY,EAAC,MAAM,CAAC;QAC5B,WAAW,EAAE,WAAW,CAAC,QAAQ,EAAE;QACnC,MAAM;QACN,aAAa;KACd,CAAA;AACH,CAAC"}

package/lib/endpoints.d.ts

@@ -0,0 +1,12 @@
+declare const PUBLIC_GOOD_ID = "public-good";
+declare const GITHUB_ID = "github";
+export type SigstoreInstance = typeof PUBLIC_GOOD_ID | typeof GITHUB_ID;
+export type Endpoints = {
+    fulcioURL: string;
+    rekorURL?: string;
+    tsaServerURL?: string;
+};
+export declare const SIGSTORE_PUBLIC_GOOD: Endpoints;
+export declare const SIGSTORE_GITHUB: Endpoints;
+export declare const signingEndpoints: (sigstore?: SigstoreInstance) => Endpoints;
+export {};

package/lib/endpoints.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signingEndpoints = exports.SIGSTORE_GITHUB = exports.SIGSTORE_PUBLIC_GOOD = void 0;
+const github = __importStar(require("@actions/github"));
+const PUBLIC_GOOD_ID = 'public-good';
+const GITHUB_ID = 'github';
+const FULCIO_PUBLIC_GOOD_URL = 'https://fulcio.sigstore.dev';
+const REKOR_PUBLIC_GOOD_URL = 'https://rekor.sigstore.dev';
+const FULCIO_INTERNAL_URL = 'https://fulcio.githubapp.com';
+const TSA_INTERNAL_URL = 'https://timestamp.githubapp.com';
+exports.SIGSTORE_PUBLIC_GOOD = {
+    fulcioURL: FULCIO_PUBLIC_GOOD_URL,
+    rekorURL: REKOR_PUBLIC_GOOD_URL
+};
+exports.SIGSTORE_GITHUB = {
+    fulcioURL: FULCIO_INTERNAL_URL,
+    tsaServerURL: TSA_INTERNAL_URL
+};
+const signingEndpoints = (sigstore) => {
+    var _a;
+    let instance;
+    // An explicitly set instance type takes precedence, but if not set, use the
+    // repository's visibility to determine the instance type.
+    if (sigstore && [PUBLIC_GOOD_ID, GITHUB_ID].includes(sigstore)) {
+        instance = sigstore;
+    }
+    else {
+        instance =
+            ((_a = github.context.payload.repository) === null || _a === void 0 ? void 0 : _a.visibility) === 'public'
+                ? PUBLIC_GOOD_ID
+                : GITHUB_ID;
+    }
+    switch (instance) {
+        case PUBLIC_GOOD_ID:
+            return exports.SIGSTORE_PUBLIC_GOOD;
+        case GITHUB_ID:
+            return exports.SIGSTORE_GITHUB;
+    }
+};
+exports.signingEndpoints = signingEndpoints;
+//# sourceMappingURL=endpoints.js.map

package/lib/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../src/endpoints.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wDAAyC;AAEzC,MAAM,cAAc,GAAG,aAAa,CAAA;AACpC,MAAM,SAAS,GAAG,QAAQ,CAAA;AAE1B,MAAM,sBAAsB,GAAG,6BAA6B,CAAA;AAC5D,MAAM,qBAAqB,GAAG,4BAA4B,CAAA;AAE1D,MAAM,mBAAmB,GAAG,8BAA8B,CAAA;AAC1D,MAAM,gBAAgB,GAAG,iCAAiC,CAAA;AAU7C,QAAA,oBAAoB,GAAc;IAC7C,SAAS,EAAE,sBAAsB;IACjC,QAAQ,EAAE,qBAAqB;CAChC,CAAA;AAEY,QAAA,eAAe,GAAc;IACxC,SAAS,EAAE,mBAAmB;IAC9B,YAAY,EAAE,gBAAgB;CAC/B,CAAA;AAEM,MAAM,gBAAgB,GAAG,CAAC,QAA2B,EAAa,EAAE;;IACzE,IAAI,QAA0B,CAAA;IAE9B,4EAA4E;IAC5E,0DAA0D;IAC1D,IAAI,QAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAC9D,QAAQ,GAAG,QAAQ,CAAA;KACpB;SAAM;QACL,QAAQ;YACN,CAAA,MAAA,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,0CAAE,UAAU,MAAK,QAAQ;gBACxD,CAAC,CAAC,cAAc;gBAChB,CAAC,CAAC,SAAS,CAAA;KAChB;IAED,QAAQ,QAAQ,EAAE;QAChB,KAAK,cAAc;YACjB,OAAO,4BAAoB,CAAA;QAC7B,KAAK,SAAS;YACZ,OAAO,uBAAe,CAAA;KACzB;AACH,CAAC,CAAA;AApBY,QAAA,gBAAgB,oBAoB5B"}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export { AttestOptions, attest } from './attest';
+export { AttestProvenanceOptions, attestProvenance, buildSLSAProvenancePredicate } from './provenance';
+export type { SerializedBundle } from '@sigstore/bundle';
+export type { Attestation, Predicate, Subject } from './shared.types';

package/lib/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSLSAProvenancePredicate = exports.attestProvenance = exports.attest = void 0;
+var attest_1 = require("./attest");
+Object.defineProperty(exports, "attest", { enumerable: true, get: function () { return attest_1.attest; } });
+var provenance_1 = require("./provenance");
+Object.defineProperty(exports, "attestProvenance", { enumerable: true, get: function () { return provenance_1.attestProvenance; } });
+Object.defineProperty(exports, "buildSLSAProvenancePredicate", { enumerable: true, get: function () { return provenance_1.buildSLSAProvenancePredicate; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAA8C;AAAvB,gGAAA,MAAM,OAAA;AAC7B,2CAIqB;AAFnB,8GAAA,gBAAgB,OAAA;AAChB,0HAAA,4BAA4B,OAAA"}

package/lib/intoto.d.ts

@@ -0,0 +1,18 @@
+import { Predicate, Subject } from './shared.types';
+/**
+ * An in-toto statement.
+ * https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md
+ */
+export type InTotoStatement = {
+    _type: string;
+    subject: Subject[];
+    predicateType: string;
+    predicate: object;
+};
+/**
+ * Assembles the given subject and predicate into an in-toto statement.
+ * @param subject - The subject of the statement.
+ * @param predicate - The predicate of the statement.
+ * @returns The constructed in-toto statement.
+ */
+export declare const buildIntotoStatement: (subject: Subject, predicate: Predicate) => InTotoStatement;

package/lib/intoto.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildIntotoStatement = void 0;
+const INTOTO_STATEMENT_V1_TYPE = 'https://in-toto.io/Statement/v1';
+/**
+ * Assembles the given subject and predicate into an in-toto statement.
+ * @param subject - The subject of the statement.
+ * @param predicate - The predicate of the statement.
+ * @returns The constructed in-toto statement.
+ */
+const buildIntotoStatement = (subject, predicate) => {
+    return {
+        _type: INTOTO_STATEMENT_V1_TYPE,
+        subject: [subject],
+        predicateType: predicate.type,
+        predicate: predicate.params
+    };
+};
+exports.buildIntotoStatement = buildIntotoStatement;
+//# sourceMappingURL=intoto.js.map

package/lib/intoto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intoto.js","sourceRoot":"","sources":["../src/intoto.ts"],"names":[],"mappings":";;;AAEA,MAAM,wBAAwB,GAAG,iCAAiC,CAAA;AAalE;;;;;GAKG;AACI,MAAM,oBAAoB,GAAG,CAClC,OAAgB,EAChB,SAAoB,EACH,EAAE;IACnB,OAAO;QACL,KAAK,EAAE,wBAAwB;QAC/B,OAAO,EAAE,CAAC,OAAO,CAAC;QAClB,aAAa,EAAE,SAAS,CAAC,IAAI;QAC7B,SAAS,EAAE,SAAS,CAAC,MAAM;KAC5B,CAAA;AACH,CAAC,CAAA;AAVY,QAAA,oBAAoB,wBAUhC"}

package/lib/provenance.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { AttestOptions } from './attest';
+import type { Attestation, Predicate } from './shared.types';
+export type AttestProvenanceOptions = Omit<AttestOptions, 'predicate' | 'predicateType'>;
+/**
+ * Builds an SLSA (Supply Chain Levels for Software Artifacts) provenance
+ * predicate using the GitHub Actions Workflow build type.
+ * https://slsa.dev/spec/v1.0/provenance
+ * https://github.com/slsa-framework/github-actions-buildtypes/tree/main/workflow/v1
+ * @param env - The Node.js process environment variables. Defaults to
+ * `process.env`.
+ * @returns The SLSA provenance predicate.
+ */
+export declare const buildSLSAProvenancePredicate: (env?: NodeJS.ProcessEnv) => Predicate;
+/**
+ * Attests the build provenance of the provided subject. Generates the SLSA
+ * build provenance predicate, assembles it into an in-toto statement, and
+ * attests it.
+ *
+ * @param options - The options for attesting the provenance.
+ * @returns A promise that resolves to the attestation.
+ */
+export declare function attestProvenance(options: AttestProvenanceOptions): Promise<Attestation>;

package/lib/provenance.js

@@ -0,0 +1,89 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attestProvenance = exports.buildSLSAProvenancePredicate = void 0;
+const attest_1 = require("./attest");
+const SLSA_PREDICATE_V1_TYPE = 'https://slsa.dev/provenance/v1';
+const GITHUB_BUILDER_ID_PREFIX = 'https://github.com/actions/runner';
+const GITHUB_BUILD_TYPE = 'https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1';
+/**
+ * Builds an SLSA (Supply Chain Levels for Software Artifacts) provenance
+ * predicate using the GitHub Actions Workflow build type.
+ * https://slsa.dev/spec/v1.0/provenance
+ * https://github.com/slsa-framework/github-actions-buildtypes/tree/main/workflow/v1
+ * @param env - The Node.js process environment variables. Defaults to
+ * `process.env`.
+ * @returns The SLSA provenance predicate.
+ */
+const buildSLSAProvenancePredicate = (env = process.env) => {
+    const workflow = env.GITHUB_WORKFLOW_REF || '';
+    // Split just the path and ref from the workflow string.
+    // owner/repo/.github/workflows/main.yml@main =>
+    //   .github/workflows/main.yml, main
+    const [workflowPath, workflowRef] = workflow
+        .replace(`${env.GITHUB_REPOSITORY}/`, '')
+        .split('@');
+    return {
+        type: SLSA_PREDICATE_V1_TYPE,
+        params: {
+            buildDefinition: {
+                buildType: GITHUB_BUILD_TYPE,
+                externalParameters: {
+                    workflow: {
+                        ref: workflowRef,
+                        repository: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}`,
+                        path: workflowPath
+                    }
+                },
+                internalParameters: {
+                    github: {
+                        event_name: env.GITHUB_EVENT_NAME,
+                        repository_id: env.GITHUB_REPOSITORY_ID,
+                        repository_owner_id: env.GITHUB_REPOSITORY_OWNER_ID
+                    }
+                },
+                resolvedDependencies: [
+                    {
+                        uri: `git+${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}@${env.GITHUB_REF}`,
+                        digest: {
+                            gitCommit: env.GITHUB_SHA
+                        }
+                    }
+                ]
+            },
+            runDetails: {
+                builder: {
+                    id: `${GITHUB_BUILDER_ID_PREFIX}/${env.RUNNER_ENVIRONMENT}`
+                },
+                metadata: {
+                    invocationId: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}/attempts/${env.GITHUB_RUN_ATTEMPT}`
+                }
+            }
+        }
+    };
+};
+exports.buildSLSAProvenancePredicate = buildSLSAProvenancePredicate;
+/**
+ * Attests the build provenance of the provided subject. Generates the SLSA
+ * build provenance predicate, assembles it into an in-toto statement, and
+ * attests it.
+ *
+ * @param options - The options for attesting the provenance.
+ * @returns A promise that resolves to the attestation.
+ */
+function attestProvenance(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const predicate = (0, exports.buildSLSAProvenancePredicate)(process.env);
+        return (0, attest_1.attest)(Object.assign(Object.assign({}, options), { predicateType: predicate.type, predicate: predicate.params }));
+    });
+}
+exports.attestProvenance = attestProvenance;
+//# sourceMappingURL=provenance.js.map

package/lib/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAA8C;AAG9C,MAAM,sBAAsB,GAAG,gCAAgC,CAAA;AAE/D,MAAM,wBAAwB,GAAG,mCAAmC,CAAA;AACpE,MAAM,iBAAiB,GACrB,wEAAwE,CAAA;AAO1E;;;;;;;;GAQG;AACI,MAAM,4BAA4B,GAAG,CAC1C,MAAyB,OAAO,CAAC,GAAG,EACzB,EAAE;IACb,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAA;IAE9C,wDAAwD;IACxD,gDAAgD;IAChD,qCAAqC;IACrC,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,QAAQ;SACzC,OAAO,CAAC,GAAG,GAAG,CAAC,iBAAiB,GAAG,EAAE,EAAE,CAAC;SACxC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEb,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE;YACN,eAAe,EAAE;gBACf,SAAS,EAAE,iBAAiB;gBAC5B,kBAAkB,EAAE;oBAClB,QAAQ,EAAE;wBACR,GAAG,EAAE,WAAW;wBAChB,UAAU,EAAE,GAAG,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,iBAAiB,EAAE;wBAC/D,IAAI,EAAE,YAAY;qBACnB;iBACF;gBACD,kBAAkB,EAAE;oBAClB,MAAM,EAAE;wBACN,UAAU,EAAE,GAAG,CAAC,iBAAiB;wBACjC,aAAa,EAAE,GAAG,CAAC,oBAAoB;wBACvC,mBAAmB,EAAE,GAAG,CAAC,0BAA0B;qBACpD;iBACF;gBACD,oBAAoB,EAAE;oBACpB;wBACE,GAAG,EAAE,OAAO,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,UAAU,EAAE;wBAC9E,MAAM,EAAE;4BACN,SAAS,EAAE,GAAG,CAAC,UAAU;yBAC1B;qBACF;iBACF;aACF;YACD,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,EAAE,EAAE,GAAG,wBAAwB,IAAI,GAAG,CAAC,kBAAkB,EAAE;iBAC5D;gBACD,QAAQ,EAAE;oBACR,YAAY,EAAE,GAAG,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,iBAAiB,iBAAiB,GAAG,CAAC,aAAa,aAAa,GAAG,CAAC,kBAAkB,EAAE;iBACvI;aACF;SACF;KACF,CAAA;AACH,CAAC,CAAA;AAlDY,QAAA,4BAA4B,gCAkDxC;AAED;;;;;;;GAOG;AACH,SAAsB,gBAAgB,CACpC,OAAgC;;QAEhC,MAAM,SAAS,GAAG,IAAA,oCAA4B,EAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3D,OAAO,IAAA,eAAM,kCACR,OAAO,KACV,aAAa,EAAE,SAAS,CAAC,IAAI,EAC7B,SAAS,EAAE,SAAS,CAAC,MAAM,IAC3B,CAAA;IACJ,CAAC;CAAA;AATD,4CASC"}

package/lib/shared.types.d.ts

@@ -0,0 +1,15 @@
+import type { SerializedBundle } from '@sigstore/bundle';
+export type Subject = {
+    name: string;
+    digest: Record<string, string>;
+};
+export type Predicate = {
+    type: string;
+    params: object;
+};
+export type Attestation = {
+    bundle: SerializedBundle;
+    certificate: string;
+    tlogID?: string;
+    attestationID?: string;
+};

package/lib/shared.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=shared.types.js.map

package/lib/shared.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.types.js","sourceRoot":"","sources":["../src/shared.types.ts"],"names":[],"mappings":""}

package/lib/sign.d.ts

@@ -0,0 +1,43 @@
+/// <reference types="node" />
+import { Bundle } from '@sigstore/bundle';
+/**
+ * The payload to be signed (body) and its media type (type).
+ */
+export type Payload = {
+    body: Buffer;
+    type: string;
+};
+/**
+ * Options for signing a document.
+ */
+export type SignOptions = {
+    /**
+     * The URL of the Fulcio service.
+     */
+    fulcioURL: string;
+    /**
+     * The URL of the Rekor service.
+     */
+    rekorURL?: string;
+    /**
+     * The URL of the TSA (Time Stamping Authority) server.
+     */
+    tsaServerURL?: string;
+    /**
+     * The timeout duration in milliseconds when communicating with Sigstore
+     * services.
+     */
+    timeout?: number;
+    /**
+     * The number of retry attempts.
+     */
+    retry?: number;
+};
+/**
+ * Signs the provided payload with a Sigstore-issued certificate and returns the
+ * signature bundle.
+ * @param payload Payload to be signed.
+ * @param options Signing options.
+ * @returns A promise that resolves to the Sigstore signature bundle.
+ */
+export declare const signPayload: (payload: Payload, options: SignOptions) => Promise<Bundle>;

package/lib/sign.js

@@ -0,0 +1,62 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signPayload = void 0;
+const sign_1 = require("@sigstore/sign");
+const OIDC_AUDIENCE = 'sigstore';
+const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_RETRIES = 3;
+/**
+ * Signs the provided payload with a Sigstore-issued certificate and returns the
+ * signature bundle.
+ * @param payload Payload to be signed.
+ * @param options Signing options.
+ * @returns A promise that resolves to the Sigstore signature bundle.
+ */
+const signPayload = (payload, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const artifact = {
+        data: payload.body,
+        type: payload.type
+    };
+    // Sign the artifact and build the bundle
+    return initBundleBuilder(options).create(artifact);
+});
+exports.signPayload = signPayload;
+// Assembles the Sigstore bundle builder with the appropriate options
+const initBundleBuilder = (opts) => {
+    const identityProvider = new sign_1.CIContextProvider(OIDC_AUDIENCE);
+    const timeout = opts.timeout || DEFAULT_TIMEOUT;
+    const retry = opts.retry || DEFAULT_RETRIES;
+    const witnesses = [];
+    const signer = new sign_1.FulcioSigner({
+        identityProvider,
+        fulcioBaseURL: opts.fulcioURL,
+        timeout,
+        retry
+    });
+    if (opts.rekorURL) {
+        witnesses.push(new sign_1.RekorWitness({
+            rekorBaseURL: opts.rekorURL,
+            entryType: 'dsse',
+            timeout,
+            retry
+        }));
+    }
+    if (opts.tsaServerURL) {
+        witnesses.push(new sign_1.TSAWitness({
+            tsaBaseURL: opts.tsaServerURL,
+            timeout,
+            retry
+        }));
+    }
+    return new sign_1.DSSEBundleBuilder({ signer, witnesses });
+};
+//# sourceMappingURL=sign.js.map

package/lib/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,yCAQuB;AAEvB,MAAM,aAAa,GAAG,UAAU,CAAA;AAChC,MAAM,eAAe,GAAG,KAAK,CAAA;AAC7B,MAAM,eAAe,GAAG,CAAC,CAAA;AAqCzB;;;;;;GAMG;AACI,MAAM,WAAW,GAAG,CACzB,OAAgB,EAChB,OAAoB,EACH,EAAE;IACnB,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAA;IAED,yCAAyC;IACzC,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;AACpD,CAAC,CAAA,CAAA;AAXY,QAAA,WAAW,eAWvB;AAED,qEAAqE;AACrE,MAAM,iBAAiB,GAAG,CAAC,IAAiB,EAAiB,EAAE;IAC7D,MAAM,gBAAgB,GAAG,IAAI,wBAAiB,CAAC,aAAa,CAAC,CAAA;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,CAAA;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,CAAA;IAC3C,MAAM,SAAS,GAAc,EAAE,CAAA;IAE/B,MAAM,MAAM,GAAG,IAAI,mBAAY,CAAC;QAC9B,gBAAgB;QAChB,aAAa,EAAE,IAAI,CAAC,SAAS;QAC7B,OAAO;QACP,KAAK;KACN,CAAC,CAAA;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE;QACjB,SAAS,CAAC,IAAI,CACZ,IAAI,mBAAY,CAAC;YACf,YAAY,EAAE,IAAI,CAAC,QAAQ;YAC3B,SAAS,EAAE,MAAM;YACjB,OAAO;YACP,KAAK;SACN,CAAC,CACH,CAAA;KACF;IAED,IAAI,IAAI,CAAC,YAAY,EAAE;QACrB,SAAS,CAAC,IAAI,CACZ,IAAI,iBAAU,CAAC;YACb,UAAU,EAAE,IAAI,CAAC,YAAY;YAC7B,OAAO;YACP,KAAK;SACN,CAAC,CACH,CAAA;KACF;IAED,OAAO,IAAI,wBAAiB,CAAC,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC,CAAA;AACnD,CAAC,CAAA"}

package/lib/store.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes an attestation to the repository's attestations endpoint.
+ * @param attestation - The attestation to write.
+ * @param token - The GitHub token for authentication.
+ * @returns The ID of the attestation.
+ * @throws Error if the attestation fails to persist.
+ */
+export declare const writeAttestation: (attestation: unknown, token: string) => Promise<string>;

package/lib/store.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeAttestation = void 0;
+const github = __importStar(require("@actions/github"));
+const make_fetch_happen_1 = __importDefault(require("make-fetch-happen"));
+const CREATE_ATTESTATION_REQUEST = 'POST /repos/{owner}/{repo}/attestations';
+/**
+ * Writes an attestation to the repository's attestations endpoint.
+ * @param attestation - The attestation to write.
+ * @param token - The GitHub token for authentication.
+ * @returns The ID of the attestation.
+ * @throws Error if the attestation fails to persist.
+ */
+const writeAttestation = (attestation, token) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const octokit = github.getOctokit(token, { request: { fetch: make_fetch_happen_1.default } });
+    try {
+        const response = yield octokit.request(CREATE_ATTESTATION_REQUEST, {
+            owner: github.context.repo.owner,
+            repo: github.context.repo.repo,
+            data: { bundle: attestation }
+        });
+        return (_a = response.data) === null || _a === void 0 ? void 0 : _a.id;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : err;
+        throw new Error(`Failed to persist attestation: ${message}`);
+    }
+});
+exports.writeAttestation = writeAttestation;
+//# sourceMappingURL=store.js.map

package/lib/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wDAAyC;AACzC,0EAAqC;AAErC,MAAM,0BAA0B,GAAG,yCAAyC,CAAA;AAE5E;;;;;;GAMG;AACI,MAAM,gBAAgB,GAAG,CAC9B,WAAoB,EACpB,KAAa,EACI,EAAE;;IACnB,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,EAAC,OAAO,EAAE,EAAC,KAAK,EAAL,2BAAK,EAAC,EAAC,CAAC,CAAA;IAE5D,IAAI;QACF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,0BAA0B,EAAE;YACjE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK;YAChC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI;YAC9B,IAAI,EAAE,EAAC,MAAM,EAAE,WAAW,EAAC;SAC5B,CAAC,CAAA;QAEF,OAAO,MAAA,QAAQ,CAAC,IAAI,0CAAE,EAAE,CAAA;KACzB;IAAC,OAAO,GAAG,EAAE;QACZ,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAA;QACxD,MAAM,IAAI,KAAK,CAAC,kCAAkC,OAAO,EAAE,CAAC,CAAA;KAC7D;AACH,CAAC,CAAA,CAAA;AAlBY,QAAA,gBAAgB,oBAkB5B"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@actions/attest",
+  "version": "1.0.0",
+  "description": "Actions attestation lib",
+  "keywords": [
+    "github",
+    "actions",
+    "attestation"
+  ],
+  "homepage": "https://github.com/actions/toolkit/tree/main/packages/attest",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/actions/toolkit.git",
+    "directory": "packages/attest"
+  },
+  "scripts": {
+    "test": "echo \"Error: run tests from root\" && exit 1",
+    "tsc": "tsc"
+  },
+  "bugs": {
+    "url": "https://github.com/actions/toolkit/issues"
+  },
+  "devDependencies": {
+    "@sigstore/mock": "^0.6.5",
+    "@sigstore/rekor-types": "^2.0.0",
+    "@types/make-fetch-happen": "^10.0.4",
+    "nock": "^13.5.1"
+  },
+  "dependencies": {
+    "@actions/github": "^6.0.0",
+    "@sigstore/bundle": "^2.2.0",
+    "@sigstore/sign": "^2.2.3",
+    "make-fetch-happen": "^13.0.0"
+  }
+}