@effected/sbom 0.9.1 → 0.10.0

package/IdentityToken.js

@@ -24,13 +24,21 @@ var IdentityTokenError = class extends Schema.TaggedError()("IdentityTokenError"
 /** The token every double answers with unless a test says otherwise. */
 const TEST_TOKEN = "test-identity-token";
 /**
-* A source of workload identity tokens.
+* A source of workload identity tokens (OIDC), the input `SigstoreSigner` needs
+* to obtain a signing certificate.
+*
+* @remarks
+* In GitHub Actions, provide `ActionsIdentityToken.layer` from
+* `@effected/github-actions`. A consumer that already holds a token uses
+* {@link (IdentityToken:class).layerStatic}; tests use
+* {@link (IdentityToken:class).layerTest}.
 *
 * @example
 * ```ts
 * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
 * import { Layer } from "effect";
 *
+* const token = process.env.OIDC_TOKEN ?? "";
 * const layer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(token)));
 * ```
 *

package/InTotoStatement.js

@@ -45,7 +45,7 @@ const parseResult = (value) => {
 * A deliberate small duplication rather than a shared package: `@effected/github`
 * types the same value structurally on its attestation surface, and dragging a
 * package across that seam to share one branded string would cost more than the
-* duplication does. Recorded under the program's shared-vocabulary rule.
+* duplication does.
 *
 * @public
 */
@@ -96,12 +96,16 @@ var InTotoSubject = class InTotoSubject extends Schema.Class("InTotoSubject")({
 * @example
 * ```ts
 * import { InTotoStatement, Sha256Digest, SlsaProvenance } from "@effected/sbom";
+* import { Effect } from "effect";
 *
-* const statement = InTotoStatement.forSubject({
-*   name: "pkg:npm/%40scope/pkg@1.0.0",
-*   digest,
-*   predicateType: SlsaProvenance.predicateType,
-*   predicate: provenance,
+* const program = Effect.gen(function* () {
+*   const digest = yield* Sha256Digest.parse("ab".repeat(32));
+*   return InTotoStatement.forSubject({
+*     name: "pkg:npm/%40scope/pkg@1.0.0",
+*     digest,
+*     predicateType: SlsaProvenance.predicateType,
+*     predicate: {}, // a SlsaProvenance, a BOM, or any predicate body
+*   });
 * });
 * ```
 *

package/NtiaReport.js

@@ -102,10 +102,13 @@ const timestamp = (document) => {
 *
 * @example
 * ```ts
-* import { NtiaReport } from "@effected/sbom";
+* import { Component, NtiaReport, Sbom } from "@effected/sbom";
 *
-* const report = NtiaReport.of(document);
-* if (!report.compliant) yield* Effect.logWarning(`SBOM missing: ${report.missing.join(", ")}`);
+* const root = Component.make({ type: "library", name: "lib", version: "1.0.0" });
+* const report = NtiaReport.of(Sbom.generate({ root, components: [] }));
+*
+* report.compliant; // => false
+* report.missing; // => ["supplierName", "uniqueIdentifier", "sbomAuthor", "timestamp"]
 * ```
 *
 * @public

package/README.md

@@ -7,10 +7,10 @@
 
 Supply-chain artifacts for [Effect](https://effect.website) v4: a CycloneDX 1.6 SBOM, an NTIA minimum-elements report, in-toto statements, SLSA provenance, and Sigstore DSSE signing. `Sbom.generate` and `Sbom.toJson` are total, plain functions — assembling and serializing a document cannot fail, so the package's only error channel belongs to `Sbom.write`, the one member that touches a filesystem. Signing is a separate, deliberately walled-off capability: a consumer that only ever emits an SBOM never reaches `@sigstore/*` or its Fulcio/Rekor network calls.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
@@ -53,7 +53,7 @@ declare const pkg: Package;
 const root = SbomMetadataSource.rootComponent(pkg);
 const metadata = SbomMetadataSource.fromPackage(pkg, { timestamp: new Date().toISOString() });
 const components = [
-  SbomMetadataSource.componentFor({ name: "effect", version: "4.0.0-rc.109", license: "MIT" }),
+  SbomMetadataSource.componentFor({ name: "effect", version: "4.0.0", license: "MIT" }),
 ];
 
 const document = Sbom.generate({ root, components, metadata });

package/Sbom.js

@@ -57,10 +57,11 @@ const write = Effect.fn("Sbom.write")(function* (document, path, options) {
 *
 * @example
 * ```ts
-* import { Sbom } from "@effected/sbom";
+* import { Component, Sbom } from "@effected/sbom";
 *
-* const document = Sbom.generate({ root, components });
-* const json = Sbom.toJson(document);
+* const root = Component.make({ type: "application", name: "app", version: "1.0.0" });
+* const document = Sbom.generate({ root, components: [] });
+* const json = Sbom.toJson(document); // CycloneDX 1.6 JSON text
 * ```
 *
 * @public
@@ -89,7 +90,8 @@ var Sbom = class {
 	* Write a document to `path` as canonical JSON.
 	*
 	* @remarks
-	* The one fallible member. It does not create parent directories — a caller
+	* The one fallible member; it fails with {@link SbomWriteError} and requires
+	* `FileSystem` in `R`. It does not create parent directories — a caller
 	* that wants one creates it, so the failure mode stays "the path you gave me
 	* is not writable" rather than "something was created somewhere".
 	*/

package/SbomDocument.js

@@ -84,7 +84,7 @@ var Supplier = class extends Schema.Class("Supplier")({
 * @remarks
 * `bomRef` is spelled **`bom-ref`** in the emitted JSON; the rename happens in
 * `Sbom.toJson`. Emitting `bomRef` produces a document that looks
-* correct and validates wrong, which is why a test pins the key name.
+* correct and validates wrong.
 *
 * @public
 */

package/SbomMetadataSource.js

@@ -108,11 +108,16 @@ const merge = (base, override) => {
 *
 * @example
 * ```ts
-* import { Sbom, SbomMetadataSource } from "@effected/sbom";
+* import { Package, Sbom, SbomMetadataSource, Supplier } from "@effected/sbom";
+* import { Effect } from "effect";
 *
-* const root = SbomMetadataSource.rootComponent(pkg, { supplier });
-* const metadata = SbomMetadataSource.fromPackage(pkg, { supplier, timestamp });
-* const document = Sbom.generate({ root, components, metadata });
+* const program = Effect.gen(function* () {
+*   const pkg = yield* Package.decode({ name: "@acme/app", version: "1.0.0", license: "MIT" });
+*   const supplier = Supplier.make({ name: "Acme Inc." });
+*   const root = SbomMetadataSource.rootComponent(pkg, { supplier });
+*   const metadata = SbomMetadataSource.fromPackage(pkg, { supplier, timestamp: "2026-01-01T00:00:00Z" });
+*   return Sbom.generate({ root, components: [], metadata });
+* });
 * ```
 *
 * @public
@@ -184,10 +189,8 @@ var SbomMetadataSource = class {
 	* A copyright statement for a holder and a year, or a span of years.
 	*
 	* @remarks
-	* The year is an **argument**. The predecessor defaulted it to
-	* `new Date().getFullYear()`, which made its output untestable and its
-	* purity a claim rather than a property; the ambient read belongs at the
-	* caller's edge.
+	* The year is an **argument**: nothing here reads the clock, so the output is
+	* deterministic. Read the ambient year at the caller's edge.
 	*/
 	static formatCopyright = formatCopyright;
 	/**

package/SigstoreBundle.js

@@ -24,8 +24,8 @@ const IN_TOTO_PAYLOAD_TYPE = "application/vnd.in-toto+json";
 * @remarks
 * `verificationMaterial` and `dsseEnvelope` are `unknown` because their shapes
 * belong to the Sigstore protobuf specifications, and re-declaring them here
-* would be a second, drifting copy of a wire format we do not own. The bundle
-* is opaque to everything that merely stores or forwards it.
+* would be a second, drifting copy of a wire format this package does not own.
+* The bundle is opaque to everything that merely stores or forwards it.
 *
 * `mediaType` is carried through from what the builder produced rather than
 * asserted — the version is the producer's statement about the bundle, and a

package/SigstoreSigner.js

@@ -12,9 +12,7 @@ import { DSSEBundleBuilder, FulcioSigner, RekorWitness } from "@sigstore/sign";
 * It lives here, not at the call site, because it is the **signing protocol's**
 * requirement rather than the caller's knowledge — which is why
 * {@link SigstoreSignerShape.sign} takes only a statement and asks the identity
-* contract for a token. Considered and rejected: `sign(statement, { token })`,
-* which reads simpler and forces every caller to learn a constant that is none
-* of its business.
+* contract for a token.
 *
 * @public
 */
@@ -51,14 +49,6 @@ var SigningError = class extends Schema.TaggedError()("SigningError", {
 		return `Failed to sign the statement (${this.kind})`;
 	}
 };
-/**
-* Attribute a `@sigstore/sign` failure to a step.
-*
-* `InternalError` carries a `code`, which is a far better signal than the
-* message text the predecessor scraped. An unrecognized failure is `bundle` —
-* literally "the bundle did not get built" — rather than being guessed into a
-* step it may not belong to.
-*/
 const kindOf = (cause) => {
 	const code = cause?.code;
 	if (typeof code !== "string") return "bundle";
@@ -113,17 +103,28 @@ const unstubbed = () => {
 	throw new Error("SigstoreSigner.makeTest: sign() was called but not stubbed — a fabricated bundle would be a signature-shaped lie. Pass a `sign` override, or drive the real builder through SigstoreSigner.layerWith({ signer, witnesses }).");
 };
 /**
-* Sigstore signing.
+* Signs an in-toto statement into a Sigstore DSSE bundle, using a Fulcio
+* certificate and a Rekor transparency-log entry.
+*
+* @remarks
+* Fails with {@link SigningError}. The live {@link (SigstoreSigner:class).layer}
+* requires {@link IdentityToken} in `R`.
 *
 * @example
 * ```ts
+* import type { InTotoStatement } from "@effected/sbom";
 * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
-* import { Effect, Layer } from "effect";
+* import { Effect, Layer, Redacted } from "effect";
+*
+* const sign = (statement: InTotoStatement) =>
+*   Effect.gen(function* () {
+*     const signer = yield* SigstoreSigner;
+*     return yield* signer.sign(statement);
+*   });
 *
-* const program = Effect.gen(function* () {
-*   const signer = yield* SigstoreSigner;
-*   return yield* signer.sign(statement);
-* });
+* const live = SigstoreSigner.layer.pipe(
+*   Layer.provide(IdentityToken.layerStatic(Redacted.make(process.env.OIDC_TOKEN ?? ""))),
+* );
 * ```
 *
 * @public

package/SlsaProvenance.js

@@ -90,7 +90,20 @@ const workflowPathOf = (input) => input.workflowRef.replace(`${input.repository}
 * ```ts
 * import { SlsaProvenance } from "@effected/sbom";
 *
-* const provenance = SlsaProvenance.forGitHubWorkflow(claims);
+* const provenance = SlsaProvenance.forGitHubWorkflow({
+*   serverUrl: "https://github.com",
+*   repository: "acme/app",
+*   ref: "refs/heads/main",
+*   sha: "0123456789abcdef0123456789abcdef01234567",
+*   eventName: "push",
+*   workflowRef: "acme/app/.github/workflows/release.yml@refs/heads/main",
+*   jobWorkflowRef: "acme/app/.github/workflows/release.yml@refs/heads/main",
+*   repositoryId: "1",
+*   repositoryOwnerId: "2",
+*   runnerEnvironment: "github-hosted",
+*   runId: "3",
+*   runAttempt: "1",
+* });
 * ```
 *
 * @public

package/index.d.ts

@@ -38,13 +38,21 @@ interface IdentityTokenShape {
 }
 declare const IdentityToken_base: Context.ServiceClass<IdentityToken, "@effected/sbom/IdentityToken", IdentityTokenShape>;
 /**
- * A source of workload identity tokens.
+ * A source of workload identity tokens (OIDC), the input `SigstoreSigner` needs
+ * to obtain a signing certificate.
+ *
+ * @remarks
+ * In GitHub Actions, provide `ActionsIdentityToken.layer` from
+ * `@effected/github-actions`. A consumer that already holds a token uses
+ * {@link (IdentityToken:class).layerStatic}; tests use
+ * {@link (IdentityToken:class).layerTest}.
  *
  * @example
  * ```ts
  * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
  * import { Layer } from "effect";
  *
+ * const token = process.env.OIDC_TOKEN ?? "";
  * const layer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(token)));
  * ```
  *
@@ -124,7 +132,7 @@ export declare class InvalidSha256DigestError extends InvalidSha256DigestError_b
  * A deliberate small duplication rather than a shared package: `@effected/github`
  * types the same value structurally on its attestation surface, and dragging a
  * package across that seam to share one branded string would cost more than the
- * duplication does. Recorded under the program's shared-vocabulary rule.
+ * duplication does.
  *
  * @public
  */
@@ -169,7 +177,7 @@ export declare class InTotoSubject extends InTotoSubject_base {
 /**
  * Input to {@link (InTotoStatement:class).of}.
  *
- * @remarks
+ * @privateRemarks
  * The two predicate members are spelled out here and again on
  * {@link InTotoSubjectInput} rather than shared through a base interface: an
  * internal type named on a `@public` signature is a forgotten export, and a
@@ -227,12 +235,16 @@ declare const InTotoStatement_base: Schema.Class<InTotoStatement, Schema.Struct<
  * @example
  * ```ts
  * import { InTotoStatement, Sha256Digest, SlsaProvenance } from "@effected/sbom";
+ * import { Effect } from "effect";
  *
- * const statement = InTotoStatement.forSubject({
- *   name: "pkg:npm/%40scope/pkg@1.0.0",
- *   digest,
- *   predicateType: SlsaProvenance.predicateType,
- *   predicate: provenance,
+ * const program = Effect.gen(function* () {
+ *   const digest = yield* Sha256Digest.parse("ab".repeat(32));
+ *   return InTotoStatement.forSubject({
+ *     name: "pkg:npm/%40scope/pkg@1.0.0",
+ *     digest,
+ *     predicateType: SlsaProvenance.predicateType,
+ *     predicate: {}, // a SlsaProvenance, a BOM, or any predicate body
+ *   });
  * });
  * ```
  *
@@ -367,7 +379,7 @@ declare const Component_base: Schema.Class<Component, Schema.Struct<{
  * @remarks
  * `bomRef` is spelled **`bom-ref`** in the emitted JSON; the rename happens in
  * `Sbom.toJson`. Emitting `bomRef` produces a document that looks
- * correct and validates wrong, which is why a test pins the key name.
+ * correct and validates wrong.
  *
  * @public
  */
@@ -452,10 +464,13 @@ declare const NtiaReport_base: Schema.Class<NtiaReport, Schema.Struct<{
  *
  * @example
  * ```ts
- * import { NtiaReport } from "@effected/sbom";
+ * import { Component, NtiaReport, Sbom } from "@effected/sbom";
  *
- * const report = NtiaReport.of(document);
- * if (!report.compliant) yield* Effect.logWarning(`SBOM missing: ${report.missing.join(", ")}`);
+ * const root = Component.make({ type: "library", name: "lib", version: "1.0.0" });
+ * const report = NtiaReport.of(Sbom.generate({ root, components: [] }));
+ *
+ * report.compliant; // => false
+ * report.missing; // => ["supplierName", "uniqueIdentifier", "sbomAuthor", "timestamp"]
  * ```
  *
  * @public
@@ -518,10 +533,11 @@ export declare class SbomWriteError extends SbomWriteError_base {
  *
  * @example
  * ```ts
- * import { Sbom } from "@effected/sbom";
+ * import { Component, Sbom } from "@effected/sbom";
  *
- * const document = Sbom.generate({ root, components });
- * const json = Sbom.toJson(document);
+ * const root = Component.make({ type: "application", name: "app", version: "1.0.0" });
+ * const document = Sbom.generate({ root, components: [] });
+ * const json = Sbom.toJson(document); // CycloneDX 1.6 JSON text
  * ```
  *
  * @public
@@ -550,7 +566,8 @@ export declare class Sbom {
    * Write a document to `path` as canonical JSON.
    *
    * @remarks
-   * The one fallible member. It does not create parent directories — a caller
+   * The one fallible member; it fails with {@link SbomWriteError} and requires
+   * `FileSystem` in `R`. It does not create parent directories — a caller
    * that wants one creates it, so the failure mode stays "the path you gave me
    * is not writable" rather than "something was created somewhere".
    */
@@ -615,7 +632,7 @@ interface ComponentInput {
 interface CopyrightYears {
   /** The first year of the range. Omit for a single-year statement. */
   readonly startYear?: number | undefined;
-  /** The year the statement is current through — the caller's clock read, never ours. */
+  /** The year the statement is current through, supplied by the caller. */
   readonly year: number;
 }
 /**
@@ -623,11 +640,16 @@ interface CopyrightYears {
  *
  * @example
  * ```ts
- * import { Sbom, SbomMetadataSource } from "@effected/sbom";
+ * import { Package, Sbom, SbomMetadataSource, Supplier } from "@effected/sbom";
+ * import { Effect } from "effect";
  *
- * const root = SbomMetadataSource.rootComponent(pkg, { supplier });
- * const metadata = SbomMetadataSource.fromPackage(pkg, { supplier, timestamp });
- * const document = Sbom.generate({ root, components, metadata });
+ * const program = Effect.gen(function* () {
+ *   const pkg = yield* Package.decode({ name: "@acme/app", version: "1.0.0", license: "MIT" });
+ *   const supplier = Supplier.make({ name: "Acme Inc." });
+ *   const root = SbomMetadataSource.rootComponent(pkg, { supplier });
+ *   const metadata = SbomMetadataSource.fromPackage(pkg, { supplier, timestamp: "2026-01-01T00:00:00Z" });
+ *   return Sbom.generate({ root, components: [], metadata });
+ * });
  * ```
  *
  * @public
@@ -699,10 +721,8 @@ export declare class SbomMetadataSource {
    * A copyright statement for a holder and a year, or a span of years.
    *
    * @remarks
-   * The year is an **argument**. The predecessor defaulted it to
-   * `new Date().getFullYear()`, which made its output untestable and its
-   * purity a claim rather than a property; the ambient read belongs at the
-   * caller's edge.
+   * The year is an **argument**: nothing here reads the clock, so the output is
+   * deterministic. Read the ambient year at the caller's edge.
    */
   static readonly formatCopyright: (holder: string, years: CopyrightYears) => string;
   /**
@@ -749,8 +769,8 @@ declare const SigstoreBundle_base: Schema.Class<SigstoreBundle, Schema.Struct<{
  * @remarks
  * `verificationMaterial` and `dsseEnvelope` are `unknown` because their shapes
  * belong to the Sigstore protobuf specifications, and re-declaring them here
- * would be a second, drifting copy of a wire format we do not own. The bundle
- * is opaque to everything that merely stores or forwards it.
+ * would be a second, drifting copy of a wire format this package does not own.
+ * The bundle is opaque to everything that merely stores or forwards it.
  *
  * `mediaType` is carried through from what the builder produced rather than
  * asserted — the version is the producer's statement about the bundle, and a
@@ -770,9 +790,7 @@ export declare class SigstoreBundle extends SigstoreBundle_base {}
  * It lives here, not at the call site, because it is the **signing protocol's**
  * requirement rather than the caller's knowledge — which is why
  * {@link SigstoreSignerShape.sign} takes only a statement and asks the identity
- * contract for a token. Considered and rejected: `sign(statement, { token })`,
- * which reads simpler and forces every caller to learn a constant that is none
- * of its business.
+ * contract for a token.
  *
  * @public
  */
@@ -848,17 +866,28 @@ interface SigstoreSignerShape {
 }
 declare const SigstoreSigner_base: Context.ServiceClass<SigstoreSigner, "@effected/sbom/SigstoreSigner", SigstoreSignerShape>;
 /**
- * Sigstore signing.
+ * Signs an in-toto statement into a Sigstore DSSE bundle, using a Fulcio
+ * certificate and a Rekor transparency-log entry.
+ *
+ * @remarks
+ * Fails with {@link SigningError}. The live {@link (SigstoreSigner:class).layer}
+ * requires {@link IdentityToken} in `R`.
  *
  * @example
  * ```ts
+ * import type { InTotoStatement } from "@effected/sbom";
  * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
- * import { Effect, Layer } from "effect";
+ * import { Effect, Layer, Redacted } from "effect";
  *
- * const program = Effect.gen(function* () {
- *   const signer = yield* SigstoreSigner;
- *   return yield* signer.sign(statement);
- * });
+ * const sign = (statement: InTotoStatement) =>
+ *   Effect.gen(function* () {
+ *     const signer = yield* SigstoreSigner;
+ *     return yield* signer.sign(statement);
+ *   });
+ *
+ * const live = SigstoreSigner.layer.pipe(
+ *   Layer.provide(IdentityToken.layerStatic(Redacted.make(process.env.OIDC_TOKEN ?? ""))),
+ * );
  * ```
  *
  * @public
@@ -970,8 +999,7 @@ export declare class SlsaRunDetails extends SlsaRunDetails_base {}
  *
  * @remarks
  * A plain input record, **not** a service. There is nothing to swap and no IO
- * to invert — it is the argument to a data constructor, and inventing a seam
- * for one would repeat a mistake this program already reversed once.
+ * to invert — it is the argument to a data constructor.
  *
  * Fields are camelCase here and re-spelled to the platform's claim names where
  * the predicate demands it, so a caller reads its own vocabulary and the
@@ -1018,7 +1046,20 @@ declare const SlsaProvenance_base: Schema.Class<SlsaProvenance, Schema.Struct<{
  * ```ts
  * import { SlsaProvenance } from "@effected/sbom";
  *
- * const provenance = SlsaProvenance.forGitHubWorkflow(claims);
+ * const provenance = SlsaProvenance.forGitHubWorkflow({
+ *   serverUrl: "https://github.com",
+ *   repository: "acme/app",
+ *   ref: "refs/heads/main",
+ *   sha: "0123456789abcdef0123456789abcdef01234567",
+ *   eventName: "push",
+ *   workflowRef: "acme/app/.github/workflows/release.yml@refs/heads/main",
+ *   jobWorkflowRef: "acme/app/.github/workflows/release.yml@refs/heads/main",
+ *   repositoryId: "1",
+ *   repositoryOwnerId: "2",
+ *   runnerEnvironment: "github-hosted",
+ *   runId: "3",
+ *   runAttempt: "1",
+ * });
  * ```
  *
  * @public

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/sbom",
-	"version": "0.9.1",
+	"version": "0.10.0",
 	"private": false,
 	"description": "CycloneDX 1.6 SBOM construction, SLSA provenance, NTIA validation and Sigstore signing as typed services.",
 	"keywords": [
@@ -39,13 +39,13 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/package-json": "^0.19.1",
-		"@effected/spdx": "^0.10.0",
+		"@effected/package-json": "^0.20.0",
+		"@effected/spdx": "^0.11.0",
 		"@sigstore/bundle": "^5.0.0",
 		"@sigstore/sign": "^5.0.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"