@effected/sbom 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,189 @@
+# @effected/sbom
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fsbom?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/sbom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+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 beta. 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
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/sbom
+
+`@cyclonedx/cyclonedx-library` is 6.6 MB with seven optional peer dependencies for around ten symbols this package actually needs — an object model and a JSON normalizer. The parts that would justify the weight (XML output, ajv validation, SPDX expression parsing) are exactly the parts an emitter never calls, and its `spdx-expression-parse` peer would install a second SPDX engine beside `@effected/spdx`. This package owns its CycloneDX 1.6 model directly instead, conformance-tested against the published schema rather than promised by a dependency.
+
+Emitting an SBOM and signing one are different kinds of work — pure computation over a manifest versus network-bound cryptography against Fulcio and Rekor — and the module boundary follows that split exactly. `SbomDocument`, `Sbom`, `SbomMetadataSource`, `NtiaReport`, `InTotoStatement` and `SlsaProvenance` reach nothing but `effect`, `@effected/spdx` and (as a type-only import) `@effected/package-json`. Only `SigstoreSigner.ts` imports `@sigstore/*`, and it is walked by a reachability test rather than left to convention: a namespace object gathering `generate` and `sign` together would make every SBOM consumer reachable to Fulcio's HTTP stack, silently, which is why none exists here.
+
+A license is a CycloneDX **expression** field with three legal shapes — `{license:{id}}` for a catalog identifier, a one-element `[{expression}]` tuple for an expression like `MIT OR Apache-2.0`, and `{license:{name}}` for anything else — and choosing between them is `@effected/spdx`'s job (`License.isKnownId`, `isValidExpression`), never a local regex. Emitting every value as an `id` produces a document that looks right and fails validation.
+
+## Install
+
+```bash
+npm install @effected/sbom effect
+```
+
+```bash
+pnpm add @effected/sbom effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
+## Quick start
+
+Generating an SBOM needs no layer, no service and no network call:
+
+```ts
+import { Package, Sbom, SbomMetadataSource } from "@effected/sbom";
+
+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-beta.101", license: "MIT" }),
+];
+
+const document = Sbom.generate({ root, components, metadata });
+console.log(Sbom.toJson(document));
+// canonical CycloneDX 1.6 JSON — component names sorted, so two runs over
+// the same inputs produce identical bytes
+```
+
+Components are sorted by name so the document's digest — which becomes an attestation subject — does not change between runs over the same inputs for no reason.
+
+`Package`, `Person` and `Repository` come from `@effected/package-json` and are re-exported here, so naming the type `fromPackage` takes does not mean declaring a dependency you would not otherwise have. Inside `src/` the manifest types stay a type-only import; the entry point is the one place they cross as values.
+
+## NTIA compliance
+
+`NtiaReport.of` is total: it answers for every document, including one that satisfies nothing.
+
+```ts
+import { NtiaReport, SbomDocument } from "@effected/sbom";
+import { Effect } from "effect";
+
+declare const document: SbomDocument;
+
+const program = Effect.gen(function* () {
+  const report = NtiaReport.of(document);
+  if (!report.compliant) {
+    yield* Effect.logWarning(`SBOM missing: ${report.missing.join(", ")}`);
+  }
+  return report;
+});
+// report.missing: readonly NtiaElementId[] — e.g. ["sbomAuthor", "timestamp"]
+```
+
+## Provenance and attestation
+
+`InTotoStatement` and `SlsaProvenance` build the predicate an attestation wraps around an SBOM or a build. Both are pure projections of their input — nothing is read from the environment, and nothing can fail:
+
+```ts
+import { InTotoStatement, Sha256Digest, SbomMetadataSource, SlsaProvenance } from "@effected/sbom";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const digest = yield* Sha256Digest.parse("a".repeat(64));
+  const provenance = SlsaProvenance.forGitHubWorkflow({
+    serverUrl: "https://github.com",
+    repository: "acme/widget",
+    ref: "refs/heads/main",
+    sha: "abc123",
+    eventName: "push",
+    workflowRef: "acme/widget/.github/workflows/release.yml@refs/heads/main",
+    jobWorkflowRef: "acme/widget/.github/workflows/release.yml@refs/heads/main",
+    repositoryId: "1",
+    repositoryOwnerId: "1",
+    runnerEnvironment: "github-hosted",
+    runId: "1",
+    runAttempt: "1",
+  });
+
+  return InTotoStatement.forSubject({
+    name: SbomMetadataSource.npmPurl("@acme/widget", "1.0.0"),
+    digest,
+    predicateType: SlsaProvenance.predicateType,
+    predicate: provenance,
+  });
+});
+```
+
+## Signing
+
+`SigstoreSigner` fetches an identity token, exchanges it with Fulcio for a certificate, signs the statement, and (unless `witnesses: []`) logs it to Rekor — all behind one method, `sign`, over `IdentityToken`:
+
+```ts
+import { IdentityToken, InTotoStatement, SigstoreSigner } from "@effected/sbom";
+import { Effect, Layer } from "effect";
+
+declare const oidcToken: string;
+declare const statement: InTotoStatement;
+
+const program = Effect.gen(function* () {
+  const signer = yield* SigstoreSigner;
+  return yield* signer.sign(statement);
+});
+
+const SignerLayer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(oidcToken)));
+
+Effect.runPromise(program.pipe(Effect.provide(SignerLayer))).then(console.log);
+// SigstoreBundle: { mediaType, verificationMaterial, dsseEnvelope }
+```
+
+`IdentityToken` is a narrow, one-method contract deliberately smaller than any real issuer's surface, so several things can satisfy it. On a GitHub runner that is `ActionsIdentityToken.layer`, which `@effected/github-actions` ships over its own `OidcTokenIssuer` — the dependency points that way so signing never drags the Actions runtime into a consumer that only emits an SBOM. A CI system that mints its own token works the same way through `IdentityToken.layerStatic`.
+
+## Errors
+
+`SigningError.kind` names which step failed — `identity` (a workflow permissions problem), `certificate` (Fulcio), `transparencyLog` (Rekor), or `bundle` (assembly) — with the original failure preserved structurally on `cause` rather than flattened into a message:
+
+```ts
+import { SigningError } from "@effected/sbom";
+import { Effect } from "effect";
+
+declare const sign: Effect.Effect<unknown, SigningError>;
+
+const program = sign.pipe(Effect.catchTag("SigningError", (error) => Effect.logError(`${error.kind}: ${error.message}`)));
+```
+
+`Sbom.write` is the package's only other error channel (`SbomWriteError`), because assembling and serializing a document cannot fail — there is nothing in `generate` or `toJson` that reaches an error path.
+
+## Testing
+
+`SigstoreSigner.makeTest().sign` **dies** rather than fabricating a bundle: a signature-shaped lie is exactly the failure an attestation exists to prevent. A test that needs a real bundle without a network drives the real `DSSEBundleBuilder` through `SigstoreSigner.layerWith({ signer, witnesses })`. `IdentityToken.makeTest`, by contrast, **answers** — a fabricated OIDC token is a real answer to "give me a token":
+
+```ts
+import { IdentityToken } from "@effected/sbom";
+import { Effect } from "effect";
+
+const TestToken = IdentityToken.layerTest({
+  token: () => Effect.succeed("test-token"),
+});
+```
+
+## Features
+
+- `Sbom` — `generate` (total), `toJson` (total, canonical CycloneDX 1.6), and `write` (the package's one fallible member, over core `FileSystem`).
+- `SbomDocument` — the owned CycloneDX 1.6 model: `Component`, `ComponentType`, `ExternalReference`, `Contact`, `Supplier`, `SbomMetadata`.
+- `SbomMetadataSource` — manifest-derived metadata: `npmPurl`, `componentFor`, `rootComponent`, `externalReferences`, `fromPackage`, `formatCopyright`, `merge`.
+- `NtiaReport` — the seven NTIA minimum elements as a total report (`compliant`, `missing`).
+- `InTotoStatement` — `of` / `forSubject`, over `InTotoSubject` and a validated `Sha256Digest`.
+- `SlsaProvenance` — `forGitHubWorkflow`, a total projection to a SLSA Provenance v1 predicate.
+- `SigstoreSigner` — DSSE signing against Fulcio and Rekor, `layerWith` for a supplied signer/witnesses/endpoints, and a die-on-unstubbed test double.
+- `IdentityToken` — the narrow, one-method OIDC contract `SigstoreSigner` runs on; `layerStatic` for a token you already hold.
+- `SigstoreBundle` — the bundle value and media-type constants, importing nothing from `@sigstore/*`.
+
+## License
+
+[MIT](LICENSE)

package/SbomMetadataSource.js

@@ -174,6 +174,10 @@ var SbomMetadataSource = class {
 	* maintainers fill them — the one derivation that crosses from manifest
 	* vocabulary into supplier vocabulary, and only where the caller left a
 	* hole.
+	*
+	* `pkg` is a `@effected/package-json` `Package`, re-exported from
+	* this package's entry point so a caller can name the parameter type
+	* without adding `@effected/package-json` as an undeclared dependency.
 	*/
 	static fromPackage = fromPackage;
 	/**

package/index.d.ts

@@ -1,5 +1,5 @@
+import { Package, Package as Package$1, Person, Repository } from "@effected/package-json";
 import { Brand, Context, Effect, FileSystem, Layer, Redacted, Result, Schema } from "effect";
-import { Package } from "@effected/package-json";
 import { Signer, Witness } from "@sigstore/sign";
 //#region src/IdentityToken.d.ts
 declare const IdentityTokenError_base: Schema.Class<IdentityTokenError, Schema.TaggedStruct<"IdentityTokenError", {
@@ -656,7 +656,7 @@ declare class SbomMetadataSource {
    * `publisher` resolves explicit → supplier name → the manifest's author,
    * which is what lets NTIA element 6 be satisfied from a manifest alone.
    */
-  static readonly rootComponent: (pkg: Package, options?: SbomMetadataOptions) => Component;
+  static readonly rootComponent: (pkg: Package$1, options?: SbomMetadataOptions) => Component;
   /**
    * The manifest's outward links, as CycloneDX external references.
    *
@@ -670,7 +670,7 @@ declare class SbomMetadataSource {
    * `externalReference.url` is a URL, and emitting `owner/name` there is a
    * document that validates and misleads.
    */
-  static readonly externalReferences: (pkg: Package, options?: SbomMetadataOptions) => ReadonlyArray<ExternalReference>;
+  static readonly externalReferences: (pkg: Package$1, options?: SbomMetadataOptions) => ReadonlyArray<ExternalReference>;
   /**
    * Document-level metadata for a manifest.
    *
@@ -684,8 +684,12 @@ declare class SbomMetadataSource {
    * maintainers fill them — the one derivation that crosses from manifest
    * vocabulary into supplier vocabulary, and only where the caller left a
    * hole.
+   *
+   * `pkg` is a `@effected/package-json` `Package`, re-exported from
+   * this package's entry point so a caller can name the parameter type
+   * without adding `@effected/package-json` as an undeclared dependency.
    */
-  static readonly fromPackage: (pkg: Package, options?: SbomMetadataOptions) => SbomMetadata;
+  static readonly fromPackage: (pkg: Package$1, options?: SbomMetadataOptions) => SbomMetadata;
   /**
    * A copyright statement for a holder and a year, or a span of years.
    *
@@ -1030,5 +1034,5 @@ declare class SlsaProvenance extends SlsaProvenance_base {
   static forGitHubWorkflow(input: GitHubWorkflowProvenance): SlsaProvenance;
 }
 //#endregion
-export { CYCLONEDX_BOM_PREDICATE, Component, type ComponentInput, ComponentType, Contact, type CopyrightYears, ExternalReference, ExternalReferenceType, GITHUB_BUILD_TYPE, type GitHubWorkflowProvenance, IN_TOTO_PAYLOAD_TYPE, IN_TOTO_STATEMENT_V1, IdentityToken, IdentityTokenError, type IdentityTokenShape, InTotoStatement, type InTotoStatementInput, InTotoSubject, type InTotoSubjectInput, InvalidSha256DigestError, NtiaElement, NtiaElementId, NtiaReport, type PredicateType, SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE, SIGSTORE_OIDC_AUDIENCE, SLSA_PROVENANCE_V1, Sbom, SbomDocument, type SbomInput, type SbomJsonOptions, SbomMetadata, type SbomMetadataOptions, SbomMetadataSource, SbomWriteError, Sha256Digest, SigningError, SigningErrorKind, SigstoreBundle, SigstoreSigner, type SigstoreSignerOptions, type SigstoreSignerShape, SlsaBuildDefinition, SlsaProvenance, SlsaRunDetails, Supplier };
+export { CYCLONEDX_BOM_PREDICATE, Component, type ComponentInput, ComponentType, Contact, type CopyrightYears, ExternalReference, ExternalReferenceType, GITHUB_BUILD_TYPE, type GitHubWorkflowProvenance, IN_TOTO_PAYLOAD_TYPE, IN_TOTO_STATEMENT_V1, IdentityToken, IdentityTokenError, type IdentityTokenShape, InTotoStatement, type InTotoStatementInput, InTotoSubject, type InTotoSubjectInput, InvalidSha256DigestError, NtiaElement, NtiaElementId, NtiaReport, Package, Person, type PredicateType, Repository, SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE, SIGSTORE_OIDC_AUDIENCE, SLSA_PROVENANCE_V1, Sbom, SbomDocument, type SbomInput, type SbomJsonOptions, SbomMetadata, type SbomMetadataOptions, SbomMetadataSource, SbomWriteError, Sha256Digest, SigningError, SigningErrorKind, SigstoreBundle, SigstoreSigner, type SigstoreSignerOptions, type SigstoreSignerShape, SlsaBuildDefinition, SlsaProvenance, SlsaRunDetails, Supplier };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -7,5 +7,6 @@ import { SbomMetadataSource } from "./SbomMetadataSource.js";
 import { IN_TOTO_PAYLOAD_TYPE, SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE, SigstoreBundle } from "./SigstoreBundle.js";
 import { SIGSTORE_OIDC_AUDIENCE, SigningError, SigningErrorKind, SigstoreSigner } from "./SigstoreSigner.js";
 import { GITHUB_BUILD_TYPE, SLSA_PROVENANCE_V1, SlsaBuildDefinition, SlsaProvenance, SlsaRunDetails } from "./SlsaProvenance.js";
+import { Package, Person, Repository } from "@effected/package-json";
 
-export { CYCLONEDX_BOM_PREDICATE, Component, ComponentType, Contact, ExternalReference, ExternalReferenceType, GITHUB_BUILD_TYPE, IN_TOTO_PAYLOAD_TYPE, IN_TOTO_STATEMENT_V1, IdentityToken, IdentityTokenError, InTotoStatement, InTotoSubject, InvalidSha256DigestError, NtiaElement, NtiaElementId, NtiaReport, SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE, SIGSTORE_OIDC_AUDIENCE, SLSA_PROVENANCE_V1, Sbom, SbomDocument, SbomMetadata, SbomMetadataSource, SbomWriteError, Sha256Digest, SigningError, SigningErrorKind, SigstoreBundle, SigstoreSigner, SlsaBuildDefinition, SlsaProvenance, SlsaRunDetails, Supplier };
+export { CYCLONEDX_BOM_PREDICATE, Component, ComponentType, Contact, ExternalReference, ExternalReferenceType, GITHUB_BUILD_TYPE, IN_TOTO_PAYLOAD_TYPE, IN_TOTO_STATEMENT_V1, IdentityToken, IdentityTokenError, InTotoStatement, InTotoSubject, InvalidSha256DigestError, NtiaElement, NtiaElementId, NtiaReport, Package, Person, Repository, SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE, SIGSTORE_OIDC_AUDIENCE, SLSA_PROVENANCE_V1, Sbom, SbomDocument, SbomMetadata, SbomMetadataSource, SbomWriteError, Sha256Digest, SigningError, SigningErrorKind, SigstoreBundle, SigstoreSigner, SlsaBuildDefinition, SlsaProvenance, SlsaRunDetails, Supplier };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/sbom",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"description": "CycloneDX 1.6 SBOM construction, SLSA provenance, NTIA validation and Sigstore signing as typed services.",
 	"keywords": [
@@ -39,7 +39,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/package-json": "~0.6.0",
+		"@effected/package-json": "~0.6.1",
 		"@effected/spdx": "~0.1.1",
 		"@sigstore/bundle": "^5.0.0",
 		"@sigstore/sign": "^5.0.0"