@effected/sbom 0.1.0

package/index.d.ts

@@ -0,0 +1,1034 @@
+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", {
+  /** The audience the token was requested for. */
+  readonly audience: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an identity token cannot be obtained.
+ *
+ * @remarks
+ * The audience is on the error because "which audience" is the first thing a
+ * caller checks when an exchange is refused — a token minted for the wrong one
+ * fails at the certificate authority, far from here.
+ *
+ * @public
+ */
+declare class IdentityTokenError extends IdentityTokenError_base {
+  get message(): string;
+}
+/**
+ * The contract: one method, one audience, one redacted token.
+ *
+ * @remarks
+ * Deliberately smaller than any issuer's own surface. An implementation may
+ * cache, may decode claims, may do neither — none of that is this package's
+ * business, and a wider contract would make github-actions' issuer the only
+ * thing that could satisfy it.
+ *
+ * @public
+ */
+interface IdentityTokenShape {
+  /** A workload identity token for `audience`. */
+  readonly token: (audience: string) => Effect.Effect<Redacted.Redacted<string>, IdentityTokenError>;
+}
+declare const IdentityToken_base: Context.ServiceClass<IdentityToken, "@effected/sbom/IdentityToken", IdentityTokenShape>;
+/**
+ * A source of workload identity tokens.
+ *
+ * @example
+ * ```ts
+ * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
+ * import { Layer } from "effect";
+ *
+ * const layer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(token)));
+ * ```
+ *
+ * @public
+ */
+declare class IdentityToken extends IdentityToken_base {
+  /**
+   * A layer answering with a token the caller already holds.
+   *
+   * @remarks
+   * For a consumer that obtained a token by some other route — a CI system
+   * that is not GitHub Actions, or a script that exchanged one itself. The
+   * audience is **ignored**, so it is the caller's job to have minted the token
+   * for the audience it will be used with; a layer cannot check that, and
+   * pretending otherwise would be theatre.
+   */
+  static readonly layerStatic: (token: Redacted.Redacted<string> | string) => Layer.Layer<IdentityToken>;
+  /**
+   * An in-memory double.
+   *
+   * @remarks
+   * Unlike {@link (SigstoreSigner:class).makeTest}, this one **answers** rather than
+   * dying: a fabricated OIDC token is a real answer to "give me a token" in a
+   * test, where a fabricated signature would be a lie about cryptography.
+   */
+  static readonly makeTest: (overrides?: Partial<IdentityTokenShape>) => IdentityTokenShape;
+  /** {@link (IdentityToken:class).makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<IdentityTokenShape>) => Layer.Layer<IdentityToken>;
+}
+//#endregion
+//#region src/InTotoStatement.d.ts
+/**
+ * The in-toto Statement v1 type URI, stamped onto every statement this package
+ * emits.
+ *
+ * @see {@link https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md | in-toto Statement v1}
+ *
+ * @public
+ */
+declare const IN_TOTO_STATEMENT_V1: "https://in-toto.io/Statement/v1";
+/**
+ * The CycloneDX BOM predicate type, for attesting an SBOM.
+ *
+ * @public
+ */
+declare const CYCLONEDX_BOM_PREDICATE: "https://cyclonedx.org/bom";
+/**
+ * The URI naming what a statement asserts about its subjects.
+ *
+ * @remarks
+ * Deliberately an open string rather than a union: the predicate vocabulary is
+ * extensible by design, and a closed union here would refuse a valid statement
+ * for a predicate type this package has never heard of.
+ * {@link (SlsaProvenance:class).predicateType} and {@link CYCLONEDX_BOM_PREDICATE}
+ * are the two the kit produces.
+ *
+ * @public
+ */
+type PredicateType = string;
+declare const InvalidSha256DigestError_base: Schema.Class<InvalidSha256DigestError, Schema.TaggedStruct<"InvalidSha256DigestError", {
+  /** The offending input, preserved verbatim. */
+  readonly input: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a string is not a SHA-256 digest.
+ *
+ * @public
+ */
+declare class InvalidSha256DigestError extends InvalidSha256DigestError_base {
+  get message(): string;
+}
+/**
+ * A SHA-256 digest as 64 lowercase hexadecimal characters, without an
+ * algorithm prefix.
+ *
+ * @remarks
+ * 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.
+ *
+ * @public
+ */
+declare const Sha256Digest: Schema.brand<Schema.String, "Sha256Digest"> & {
+  isValid: (value: string) => boolean;
+  parseResult: (value: string) => Result.Result<Sha256Digest, InvalidSha256DigestError>;
+  parse: (value: string) => Effect.Effect<Sha256Digest, InvalidSha256DigestError, never>;
+};
+/**
+ * A SHA-256 digest as 64 lowercase hexadecimal characters.
+ *
+ * @public
+ */
+type Sha256Digest = string & Brand.Brand<"Sha256Digest">;
+declare const InTotoSubject_base: Schema.Class<InTotoSubject, Schema.Struct<{
+  /** How the subject is identified — a purl for an npm package. */
+  readonly name: Schema.String;
+  /** Algorithm to hex digest. */
+  readonly digest: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A content-addressed artifact an attestation is about.
+ *
+ * @remarks
+ * `name` is conventionally a package URL (`pkg:npm/%40scope/name@1.0.0`), but
+ * the specification requires only that it be unique within the statement.
+ * `digest` is an open algorithm → hex map because in-toto permits several; this
+ * package writes `sha256`.
+ *
+ * @public
+ */
+declare class InTotoSubject extends InTotoSubject_base {
+  /**
+   * A subject identified by a SHA-256 digest.
+   *
+   * @remarks
+   * **Total** — the digest is already validated, which is what
+   * {@link (Sha256Digest:variable).parseResult} is for.
+   */
+  static forSha256(name: string, digest: Sha256Digest): InTotoSubject;
+}
+/**
+ * Input to {@link (InTotoStatement:class).of}.
+ *
+ * @remarks
+ * 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
+ * named alias is still a named symbol. Structural duplication is the only form
+ * the API gate accepts.
+ *
+ * @public
+ */
+interface InTotoStatementInput {
+  /** The artifacts the statement is about. */
+  readonly subject: ReadonlyArray<InTotoSubject>;
+  /** What the statement asserts. */
+  readonly predicateType: PredicateType;
+  /** The assertion's body — a `SlsaProvenance`, a BOM, or a caller's own shape. */
+  readonly predicate: unknown;
+}
+/**
+ * Input to {@link (InTotoStatement:class).forSubject}.
+ *
+ * @remarks
+ * A record rather than positional arguments on purpose: `name` and
+ * `predicateType` are both strings, and a positional constructor invites a
+ * statement that silently attests the wrong thing.
+ *
+ * @public
+ */
+interface InTotoSubjectInput {
+  /** How the single subject is identified. */
+  readonly name: string;
+  /** Its SHA-256 digest. */
+  readonly digest: Sha256Digest;
+  /** What the statement asserts. */
+  readonly predicateType: PredicateType;
+  /** The assertion's body — a `SlsaProvenance`, a BOM, or a caller's own shape. */
+  readonly predicate: unknown;
+}
+declare const InTotoStatement_base: Schema.Class<InTotoStatement, Schema.Struct<{
+  /** Always the in-toto Statement v1 URI. */
+  readonly _type: Schema.Literal<"https://in-toto.io/Statement/v1">;
+  /** The artifacts attested. */
+  readonly subject: Schema.$Array<typeof InTotoSubject>;
+  /** What is being asserted about them. */
+  readonly predicateType: Schema.String;
+  /** The assertion body. */
+  readonly predicate: Schema.Unknown;
+}>, {}>;
+/**
+ * An in-toto Statement v1.
+ *
+ * @remarks
+ * `predicate` is `unknown` by design — SLSA provenance, a CycloneDX BOM and a
+ * caller's own predicate all travel here, and the statement layer has no reason
+ * to introspect any of them.
+ *
+ * @example
+ * ```ts
+ * import { InTotoStatement, Sha256Digest, SlsaProvenance } from "@effected/sbom";
+ *
+ * const statement = InTotoStatement.forSubject({
+ *   name: "pkg:npm/%40scope/pkg@1.0.0",
+ *   digest,
+ *   predicateType: SlsaProvenance.predicateType,
+ *   predicate: provenance,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class InTotoStatement extends InTotoStatement_base {
+  /** A statement over any number of subjects. **Total.** */
+  static of(input: InTotoStatementInput): InTotoStatement;
+  /** A statement over a single artifact — the common case. **Total.** */
+  static forSubject(input: InTotoSubjectInput): InTotoStatement;
+  /**
+   * The statement as JSON — the bytes a DSSE envelope carries as its payload.
+   *
+   * @remarks
+   * Compact and in a fixed key order by default, so the same statement
+   * serializes to the same bytes on every run. Pass `space` for a form meant to
+   * be read by a person.
+   */
+  toJson(options?: {
+    readonly space?: number;
+  }): string;
+}
+//#endregion
+//#region src/SbomDocument.d.ts
+/**
+ * The CycloneDX component types this package emits.
+ *
+ * @remarks
+ * A deliberate subset of the specification's fourteen: an npm SBOM describes
+ * libraries and applications. The full enum is available in the schema; adding
+ * a member here is a one-line change when something needs one.
+ *
+ * @public
+ */
+declare const ComponentType: Schema.Literals<readonly ["library", "application", "framework"]>;
+/**
+ * The decoded type of {@link (ComponentType:variable)}.
+ *
+ * @public
+ */
+type ComponentType = typeof ComponentType.Type;
+/**
+ * An external reference's kind.
+ *
+ * @remarks
+ * The four the manifest mapping produces, out of the specification's 43. Each
+ * corresponds to a `package.json` field: `vcs` ← `repository`,
+ * `issue-tracker` ← `bugs`, `website` and `documentation` ← `homepage`.
+ *
+ * @public
+ */
+declare const ExternalReferenceType: Schema.Literals<readonly ["vcs", "issue-tracker", "website", "documentation"]>;
+/**
+ * The decoded type of {@link (ExternalReferenceType:variable)}.
+ *
+ * @public
+ */
+type ExternalReferenceType = typeof ExternalReferenceType.Type;
+declare const ExternalReference_base: Schema.Class<ExternalReference, Schema.Struct<{
+  /** The reference kind. */
+  readonly type: Schema.Literals<readonly ["vcs", "issue-tracker", "website", "documentation"]>;
+  /** The URL it points at, passed through exactly as supplied. */
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * A link from a component to something outside the BOM.
+ *
+ * @public
+ */
+declare class ExternalReference extends ExternalReference_base {}
+declare const Contact_base: Schema.Class<Contact, Schema.Struct<{
+  /** The contact's name. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** Their email address. */
+  readonly email: Schema.optionalKey<Schema.String>;
+  /** Their telephone number. */
+  readonly phone: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * A point of contact — a person at a supplier, or an author of the BOM.
+ *
+ * @public
+ */
+declare class Contact extends Contact_base {}
+declare const Supplier_base: Schema.Class<Supplier, Schema.Struct<{
+  /** The supplier organization's name. */
+  readonly name: Schema.String;
+  /** Its URLs. */
+  readonly url: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  /** Its points of contact. */
+  readonly contact: Schema.optionalKey<Schema.$Array<typeof Contact>>;
+}>, {}>;
+/**
+ * The organization that supplied a component.
+ *
+ * @remarks
+ * `name` is required because `metadata.supplier.name` is **NTIA minimum
+ * element 1**; a supplier without one satisfies nothing.
+ *
+ * @public
+ */
+declare class Supplier extends Supplier_base {}
+declare const Component_base: Schema.Class<Component, Schema.Struct<{
+  /** What kind of component this is. */
+  readonly type: Schema.Literals<readonly ["library", "application", "framework"]>;
+  /** The component's name — NTIA minimum element 2. */
+  readonly name: Schema.String;
+  /** Its version — NTIA minimum element 3. */
+  readonly version: Schema.optionalKey<Schema.String>;
+  /** The package URL uniquely identifying it — NTIA minimum element 4. */
+  readonly purl: Schema.optionalKey<Schema.String>;
+  /** The identifier other parts of the document reference it by. */
+  readonly bomRef: Schema.optionalKey<Schema.String>;
+  /** A short description. */
+  readonly description: Schema.optionalKey<Schema.String>;
+  /** SPDX license identifiers or expressions. */
+  readonly licenses: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  /** Links out of the BOM. */
+  readonly externalReferences: Schema.optionalKey<Schema.$Array<typeof ExternalReference>>;
+  /** Discovery keywords — CycloneDX 1.6's `tags`, from the manifest's `keywords`. */
+  readonly tags: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  /** The component's authors. */
+  readonly authors: Schema.optionalKey<Schema.$Array<typeof Contact>>;
+  /** The entity that published it. */
+  readonly publisher: Schema.optionalKey<Schema.String>;
+  /** A copyright statement. */
+  readonly copyright: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One component in the BOM — the root, or a dependency.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare class Component extends Component_base {}
+declare const SbomMetadata_base: Schema.Class<SbomMetadata, Schema.Struct<{
+  /** When the BOM was assembled — NTIA minimum element 7. */
+  readonly timestamp: Schema.optionalKey<Schema.String>;
+  /** Who created the BOM — NTIA minimum element 6. */
+  readonly authors: Schema.optionalKey<Schema.$Array<typeof Contact>>;
+  /** The component the BOM describes. */
+  readonly component: Schema.optionalKey<typeof Component>;
+  /** Who supplied that component — NTIA minimum element 1. */
+  readonly supplier: Schema.optionalKey<typeof Supplier>;
+}>, {}>;
+/**
+ * Document-level metadata: who made the BOM, when, and about what.
+ *
+ * @public
+ */
+declare class SbomMetadata extends SbomMetadata_base {}
+declare const SbomDocument_base: Schema.Class<SbomDocument, Schema.Struct<{
+  /** Always `"CycloneDX"`. */
+  readonly bomFormat: Schema.Literal<"CycloneDX">;
+  /** Always `"1.6"`. */
+  readonly specVersion: Schema.Literal<"1.6">;
+  /** The document revision, `1` for a freshly assembled BOM. */
+  readonly version: Schema.Number;
+  /** Document metadata. */
+  readonly metadata: Schema.optionalKey<typeof SbomMetadata>;
+  /** The components the BOM describes, sorted by name. */
+  readonly components: Schema.$Array<typeof Component>;
+}>, {}>;
+/**
+ * A CycloneDX 1.6 bill of materials.
+ *
+ * @remarks
+ * Constructed by `Sbom.generate` and serialized by `Sbom.toJson`; both are
+ * total functions, because an owned model over validated values has nothing to
+ * fail at.
+ *
+ * @public
+ */
+declare class SbomDocument extends SbomDocument_base {}
+//#endregion
+//#region src/NtiaReport.d.ts
+/**
+ * The seven NTIA minimum elements, by stable identifier.
+ *
+ * @remarks
+ * A literal union rather than free text: this is what a consumer branches on,
+ * and a display name is what it renders afterwards.
+ *
+ * @public
+ */
+declare const NtiaElementId: Schema.Literals<readonly ["supplierName", "componentName", "componentVersion", "uniqueIdentifier", "dependencyRelationship", "sbomAuthor", "timestamp"]>;
+/**
+ * The decoded type of {@link (NtiaElementId:variable)}.
+ *
+ * @public
+ */
+type NtiaElementId = typeof NtiaElementId.Type;
+declare const NtiaElement_base: Schema.Class<NtiaElement, Schema.Struct<{
+  /** Which element this is. */
+  readonly id: Schema.Literals<readonly ["supplierName", "componentName", "componentVersion", "uniqueIdentifier", "dependencyRelationship", "sbomAuthor", "timestamp"]>;
+  /** Whether the document satisfies it. */
+  readonly satisfied: Schema.Boolean;
+  /** The value that satisfied it, when one did. */
+  readonly value: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One element's verdict.
+ *
+ * @public
+ */
+declare class NtiaElement extends NtiaElement_base {}
+declare const NtiaReport_base: Schema.Class<NtiaReport, Schema.Struct<{
+  /** One verdict per element, in the published order. */
+  readonly elements: Schema.$Array<typeof NtiaElement>;
+}>, {}>;
+/**
+ * A document's standing against the NTIA minimum elements.
+ *
+ * @example
+ * ```ts
+ * import { NtiaReport } from "@effected/sbom";
+ *
+ * const report = NtiaReport.of(document);
+ * if (!report.compliant) yield* Effect.logWarning(`SBOM missing: ${report.missing.join(", ")}`);
+ * ```
+ *
+ * @public
+ */
+declare class NtiaReport extends NtiaReport_base {
+  /** Whether every element is satisfied. */
+  get compliant(): boolean;
+  /** The elements the document does not satisfy, by id. */
+  get missing(): ReadonlyArray<NtiaElementId>;
+  /**
+   * Check a document. **Total** — a report is the answer for every input,
+   * including a document that satisfies nothing.
+   */
+  static of(document: SbomDocument): NtiaReport;
+}
+//#endregion
+//#region src/Sbom.d.ts
+/**
+ * Input to {@link Sbom.generate}.
+ *
+ * @public
+ */
+interface SbomInput {
+  /** The component the BOM is about. */
+  readonly root: Component;
+  /** Its dependencies, in any order — the document sorts them. */
+  readonly components: ReadonlyArray<Component>;
+  /** Document metadata. `root` is threaded onto it automatically. */
+  readonly metadata?: SbomMetadata;
+}
+/**
+ * Options for {@link Sbom.toJson}.
+ *
+ * @public
+ */
+interface SbomJsonOptions {
+  /** `JSON.stringify` indentation. Defaults to `2`; `0` emits one line. */
+  readonly space?: number;
+}
+declare const SbomWriteError_base: Schema.Class<SbomWriteError, Schema.TaggedStruct<"SbomWriteError", {
+  /** The path that could not be written. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a BOM cannot be written to disk.
+ *
+ * @remarks
+ * The package's **only** error, and it is the filesystem's rather than the
+ * emitter's — assembling and serializing a document cannot fail.
+ *
+ * @public
+ */
+declare class SbomWriteError extends SbomWriteError_base {
+  get message(): string;
+}
+/**
+ * The SBOM emitter: assemble, serialize, write.
+ *
+ * @example
+ * ```ts
+ * import { Sbom } from "@effected/sbom";
+ *
+ * const document = Sbom.generate({ root, components });
+ * const json = Sbom.toJson(document);
+ * ```
+ *
+ * @public
+ */
+declare class Sbom {
+  private constructor();
+  /**
+   * Assemble a CycloneDX 1.6 document.
+   *
+   * @remarks
+   * **Total** — no error channel, because there is nothing here that can fail.
+   * Components are sorted by name so two runs over the same inputs produce the
+   * same bytes: an SBOM's digest becomes an attestation subject, and a document
+   * that reordered itself between runs would change that digest for no reason.
+   */
+  static readonly generate: (input: SbomInput) => SbomDocument;
+  /**
+   * Serialize a document to canonical CycloneDX 1.6 JSON.
+   *
+   * @remarks
+   * **Total.** Absent optional fields are omitted rather than emitted as `null`,
+   * and `bomRef` becomes the specification's hyphenated `bom-ref`.
+   */
+  static readonly toJson: (document: SbomDocument, options?: SbomJsonOptions) => string;
+  /**
+   * Write a document to `path` as canonical JSON.
+   *
+   * @remarks
+   * The one fallible member. 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".
+   */
+  static readonly write: (document: SbomDocument, path: string, options?: SbomJsonOptions | undefined) => Effect.Effect<void, SbomWriteError, FileSystem.FileSystem>;
+}
+//#endregion
+//#region src/SbomMetadataSource.d.ts
+/**
+ * What a manifest cannot supply, and the two places an explicit value wins.
+ *
+ * @remarks
+ * A `package.json` says who wrote the software. It never says which
+ * organization supplied it, who assembled the BOM, or when — so `supplier`,
+ * `authors` and `timestamp` are explicit-only. Deriving them would fabricate
+ * three of the seven NTIA minimum elements.
+ *
+ * @public
+ */
+interface SbomMetadataOptions {
+  /** The supplying organization — NTIA minimum element 1. */
+  readonly supplier?: Supplier;
+  /** Who assembled the BOM — NTIA minimum element 6. */
+  readonly authors?: ReadonlyArray<Contact>;
+  /** When it was assembled — NTIA minimum element 7, as an ISO 8601 string. */
+  readonly timestamp?: string;
+  /** The publishing entity. Falls back to the supplier, then the manifest's author. */
+  readonly publisher?: string;
+  /** A copyright statement; {@link SbomMetadataSource.formatCopyright} builds one. */
+  readonly copyright?: string;
+  /** The documentation URL, winning over the manifest's `homepage`. */
+  readonly documentationUrl?: string;
+  /** The root component's type. Defaults to `library`. */
+  readonly type?: ComponentType;
+}
+/**
+ * The fields a dependency contributes to its component entry.
+ *
+ * @public
+ */
+interface ComponentInput {
+  /** The package name, scope included. */
+  readonly name: string;
+  /** Its resolved version. Absent produces a component with no version and no purl version segment. */
+  readonly version?: string;
+  /** An SPDX identifier or expression. */
+  readonly license?: string;
+  /** A short description. */
+  readonly description?: string;
+  /** The component type. Defaults to `library`. */
+  readonly type?: ComponentType;
+}
+/**
+ * The years a copyright statement spans.
+ *
+ * @public
+ */
+interface CopyrightYears {
+  /** The first year of the range. Omit for a single-year statement. */
+  readonly startYear?: number;
+  /** The year the statement is current through — the caller's clock read, never ours. */
+  readonly year: number;
+}
+/**
+ * Derivation of CycloneDX metadata from a `package.json` manifest.
+ *
+ * @example
+ * ```ts
+ * import { Sbom, SbomMetadataSource } from "@effected/sbom";
+ *
+ * const root = SbomMetadataSource.rootComponent(pkg, { supplier });
+ * const metadata = SbomMetadataSource.fromPackage(pkg, { supplier, timestamp });
+ * const document = Sbom.generate({ root, components, metadata });
+ * ```
+ *
+ * @public
+ */
+declare class SbomMetadataSource {
+  private constructor();
+  /**
+   * The canonical npm package URL for a name and optional version.
+   *
+   * @remarks
+   * The NTIA's "unique identifier" element, and the identifier an in-toto
+   * subject names. Exposed because a caller assembling its own components —
+   * or a statement subject — needs the same encoding this module applies.
+   */
+  static readonly npmPurl: (name: string, version?: string) => string;
+  /**
+   * A component entry for one resolved dependency.
+   *
+   * @remarks
+   * The caller assembles the component list — the kit has no second merge
+   * rule for sibling packages released in the same wave, because which
+   * versions are in flight is release planning and `@effected/workspaces`
+   * already knows it. This is the mapping that would otherwise be
+   * re-derived at every call site.
+   */
+  static readonly componentFor: (input: ComponentInput) => Component;
+  /**
+   * The root component the BOM is about, derived from its own manifest.
+   *
+   * @remarks
+   * `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;
+  /**
+   * The manifest's outward links, as CycloneDX external references.
+   *
+   * @remarks
+   * Four of the specification's 43 types, one per manifest field: `vcs` ←
+   * `repository`, `issue-tracker` ← `bugs`, `documentation` ← `homepage`,
+   * `website` ← the supplier's first URL.
+   *
+   * A `repository` value the package-json model cannot interpret produces
+   * **no** reference rather than a passed-through string: CycloneDX's
+   * `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>;
+  /**
+   * Document-level metadata for a manifest.
+   *
+   * @remarks
+   * The root component is **not** on the returned value: `Sbom.generate`
+   * threads its `root` argument onto the metadata itself, so setting it
+   * here would only be overwritten. Build the root with
+   * {@link SbomMetadataSource.rootComponent} and pass both.
+   *
+   * When the caller supplies a supplier with no contacts, the manifest's
+   * maintainers fill them — the one derivation that crosses from manifest
+   * vocabulary into supplier vocabulary, and only where the caller left a
+   * hole.
+   */
+  static readonly fromPackage: (pkg: Package, options?: SbomMetadataOptions) => SbomMetadata;
+  /**
+   * 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.
+   */
+  static readonly formatCopyright: (holder: string, years: CopyrightYears) => string;
+  /**
+   * Field-wise metadata merge: every field the override carries wins.
+   *
+   * @remarks
+   * A helper, not a policy. Which side is the override — a config file over
+   * inferred values, or the reverse — is the consumer's precedence rule,
+   * and a library that decided it would be encoding one repository's
+   * release policy.
+   */
+  static readonly merge: (base: SbomMetadata, override: SbomMetadata) => SbomMetadata;
+}
+//#endregion
+//#region src/SigstoreBundle.d.ts
+/**
+ * The Sigstore bundle media type this package produces.
+ *
+ * @remarks
+ * v0.3 with a single certificate — what `DSSEBundleBuilder` emits by default,
+ * and what GitHub's `POST /repos/{owner}/{repo}/attestations` accepts.
+ *
+ * @public
+ */
+declare const SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE: "application/vnd.dev.sigstore.bundle.v0.3+json";
+/**
+ * The DSSE payload type for an in-toto statement, per the GitHub attestations
+ * specification.
+ *
+ * @public
+ */
+declare const IN_TOTO_PAYLOAD_TYPE: "application/vnd.in-toto+json";
+declare const SigstoreBundle_base: Schema.Class<SigstoreBundle, Schema.Struct<{
+  /** The bundle's media type, usually {@link SIGSTORE_BUNDLE_V0_3_MEDIA_TYPE}. */
+  readonly mediaType: Schema.String;
+  /** The certificate and transparency-log entries a verifier checks. */
+  readonly verificationMaterial: Schema.Unknown;
+  /** The signed DSSE envelope carrying the statement. */
+  readonly dsseEnvelope: Schema.Unknown;
+}>, {}>;
+/**
+ * A signed Sigstore bundle: the wire form of an attestation.
+ *
+ * @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.
+ *
+ * `mediaType` is carried through from what the builder produced rather than
+ * asserted — the version is the producer's statement about the bundle, and a
+ * literal here would quietly lie the day a builder emits a different one.
+ *
+ * @see {@link https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto | sigstore_bundle.proto}
+ *
+ * @public
+ */
+declare class SigstoreBundle extends SigstoreBundle_base {}
+//#endregion
+//#region src/SigstoreSigner.d.ts
+/**
+ * The OIDC audience Sigstore's certificate authority requires.
+ *
+ * @remarks
+ * 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.
+ *
+ * @public
+ */
+declare const SIGSTORE_OIDC_AUDIENCE: "sigstore";
+/**
+ * Which step of signing failed.
+ *
+ * @public
+ */
+declare const SigningErrorKind: Schema.Literals<readonly ["identity", "certificate", "transparencyLog", "bundle"]>;
+/**
+ * The decoded type of {@link (SigningErrorKind:variable)}.
+ *
+ * @public
+ */
+type SigningErrorKind = typeof SigningErrorKind.Type;
+declare const SigningError_base: Schema.Class<SigningError, Schema.TaggedStruct<"SigningError", {
+  /** Which step failed. */
+  readonly kind: Schema.Literals<readonly ["identity", "certificate", "transparencyLog", "bundle"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a statement cannot be signed.
+ *
+ * @remarks
+ * Sized to what a caller can act on: an `identity` failure is a workflow
+ * permissions problem, `certificate` is Fulcio, `transparencyLog` is Rekor, and
+ * `bundle` is everything else about assembling the result. The original failure
+ * is preserved structurally on `cause` rather than flattened into a message.
+ *
+ * @public
+ */
+declare class SigningError extends SigningError_base {
+  get message(): string;
+}
+/**
+ * Where signing happens, and with what.
+ *
+ * @remarks
+ * The URL overrides exist for the Sigstore **staging** instance, which is what
+ * an opt-in end-to-end test points at. `signer` and `witnesses` replace the
+ * default Fulcio/Rekor pair outright — the seam that lets a test drive the
+ * **real** `DSSEBundleBuilder` with no network, no keys and no OIDC.
+ *
+ * @public
+ */
+interface SigstoreSignerOptions {
+  /** Fulcio's base URL. Defaults to the public-good instance. */
+  readonly fulcioBaseUrl?: string;
+  /** Rekor's base URL. Defaults to the public-good instance. */
+  readonly rekorBaseUrl?: string;
+  /** Replace the certificate signer. */
+  readonly signer?: Signer;
+  /** Replace the witnesses. An empty array signs without a transparency log. */
+  readonly witnesses?: ReadonlyArray<Witness>;
+}
+/**
+ * The signing surface.
+ *
+ * @public
+ */
+interface SigstoreSignerShape {
+  /**
+   * Sign a statement into a DSSE bundle.
+   *
+   * @remarks
+   * The identity token is fetched, used and discarded inside this call; it is
+   * `Redacted` from the contract to the moment it is handed to Fulcio, and
+   * declassified exactly once, here.
+   */
+  readonly sign: (statement: InTotoStatement) => Effect.Effect<SigstoreBundle, SigningError>;
+}
+declare const SigstoreSigner_base: Context.ServiceClass<SigstoreSigner, "@effected/sbom/SigstoreSigner", SigstoreSignerShape>;
+/**
+ * Sigstore signing.
+ *
+ * @example
+ * ```ts
+ * import { IdentityToken, SigstoreSigner } from "@effected/sbom";
+ * import { Effect, Layer } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const signer = yield* SigstoreSigner;
+ *   return yield* signer.sign(statement);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class SigstoreSigner extends SigstoreSigner_base {
+  /** Signing against the public-good Fulcio and Rekor instances. */
+  static readonly layer: Layer.Layer<SigstoreSigner, never, IdentityToken>;
+  /** {@link (SigstoreSigner:class).layer} with the signing endpoints, or the signer and witnesses, replaced. */
+  static readonly layerWith: (options: SigstoreSignerOptions) => Layer.Layer<SigstoreSigner, never, IdentityToken>;
+  /**
+   * An in-memory double whose `sign` **dies** unless stubbed.
+   *
+   * @remarks
+   * The strongest case in the kit for the die-loudly default: no honest
+   * fabricated answer exists, because a bundle that looks signed and is not is
+   * exactly the failure an attestation exists to prevent. A test that wants a
+   * real bundle without a network drives the real builder through
+   * {@link (SigstoreSigner:class).layerWith}.
+   */
+  static readonly makeTest: (overrides?: Partial<SigstoreSignerShape>) => SigstoreSignerShape;
+  /** {@link (SigstoreSigner:class).makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<SigstoreSignerShape>) => Layer.Layer<SigstoreSigner>;
+}
+//#endregion
+//#region src/SlsaProvenance.d.ts
+/**
+ * The SLSA Provenance v1 predicate type URI.
+ *
+ * @public
+ */
+declare const SLSA_PROVENANCE_V1: "https://slsa.dev/provenance/v1";
+/**
+ * The SLSA build type identifying a GitHub Actions workflow build.
+ *
+ * @remarks
+ * A published **SLSA build-type identifier** — it names a provenance shape, not
+ * an Actions runtime detail — which is why it lives with the provenance model
+ * rather than in `@effected/github-actions`.
+ *
+ * @see {@link https://github.com/slsa-framework/github-actions-buildtypes/tree/main/workflow/v1 | workflow/v1}
+ *
+ * @public
+ */
+declare const GITHUB_BUILD_TYPE: "https://actions.github.io/buildtypes/workflow/v1";
+declare const SlsaBuildDefinition_base: Schema.Class<SlsaBuildDefinition, Schema.Struct<{
+  /** The build type URI — {@link GITHUB_BUILD_TYPE} for an Actions workflow. */
+  readonly buildType: Schema.String;
+  /** Parameters an external party controls: for Actions, the workflow itself. */
+  readonly externalParameters: Schema.Struct<{
+    /** The workflow the build ran. */
+    readonly workflow: Schema.Struct<{
+      /** The git ref the workflow ran on. */
+      readonly ref: Schema.String;
+      /** The repository's browsable URL. */
+      readonly repository: Schema.String;
+      /** The workflow file's path within the repository. */
+      readonly path: Schema.String;
+    }>;
+  }>;
+  /** Parameters the build platform controls. */
+  readonly internalParameters: Schema.Struct<{
+    /** The Actions-specific half, spelled in the claim names the platform uses. */
+    readonly github: Schema.Struct<{
+      /** The event that triggered the workflow. */
+      readonly event_name: Schema.String;
+      /** The repository's numeric id. */
+      readonly repository_id: Schema.String;
+      /** The repository owner's numeric id. */
+      readonly repository_owner_id: Schema.String;
+      /** `github-hosted` or `self-hosted`. */
+      readonly runner_environment: Schema.String;
+    }>;
+  }>;
+  /** The artifacts the build consumed — for Actions, the commit it built. */
+  readonly resolvedDependencies: Schema.$Array<Schema.Struct<{
+    /** A URI naming the dependency. */
+    readonly uri: Schema.String;
+    /** Algorithm to digest; `gitCommit` for a repository. */
+    readonly digest: Schema.$Record<Schema.String, Schema.String>;
+  }>>;
+}>, {}>;
+/**
+ * How the build was invoked, and what it was invoked from.
+ *
+ * @public
+ */
+declare class SlsaBuildDefinition extends SlsaBuildDefinition_base {}
+declare const SlsaRunDetails_base: Schema.Class<SlsaRunDetails, Schema.Struct<{
+  /** The build platform's identity. */
+  readonly builder: Schema.Struct<{
+    /** A URI identifying the builder — the reusable workflow, for Actions. */
+    readonly id: Schema.String;
+  }>;
+  /** Metadata about this particular run. */
+  readonly metadata: Schema.Struct<{
+    /** A URI locating the run that produced the artifact. */
+    readonly invocationId: Schema.String;
+  }>;
+}>, {}>;
+/**
+ * Who ran the build, and the record of that run.
+ *
+ * @public
+ */
+declare class SlsaRunDetails extends SlsaRunDetails_base {}
+/**
+ * The claims and runner facts a GitHub Actions provenance predicate is built
+ * from.
+ *
+ * @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.
+ *
+ * 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
+ * emitted document keeps the specification's.
+ *
+ * @public
+ */
+interface GitHubWorkflowProvenance {
+  /** The GitHub server's base URL — `https://github.com`, or a GHES host. */
+  readonly serverUrl: string;
+  /** `owner/repo`. */
+  readonly repository: string;
+  /** The git ref built. */
+  readonly ref: string;
+  /** The commit built. */
+  readonly sha: string;
+  /** The event that triggered the workflow. */
+  readonly eventName: string;
+  /** The workflow reference: `owner/repo/.github/workflows/x.yml@ref`. */
+  readonly workflowRef: string;
+  /** The job's workflow reference, which identifies the builder. */
+  readonly jobWorkflowRef: string;
+  /** The repository's numeric id. */
+  readonly repositoryId: string;
+  /** The repository owner's numeric id. */
+  readonly repositoryOwnerId: string;
+  /** `github-hosted` or `self-hosted`. */
+  readonly runnerEnvironment: string;
+  /** The workflow run's id. */
+  readonly runId: string;
+  /** Which attempt of that run this is. */
+  readonly runAttempt: string;
+}
+declare const SlsaProvenance_base: Schema.Class<SlsaProvenance, Schema.Struct<{
+  /** What was built, and from what. */
+  readonly buildDefinition: typeof SlsaBuildDefinition;
+  /** Who built it, and when. */
+  readonly runDetails: typeof SlsaRunDetails;
+}>, {}>;
+/**
+ * A SLSA Provenance v1 predicate.
+ *
+ * @example
+ * ```ts
+ * import { SlsaProvenance } from "@effected/sbom";
+ *
+ * const provenance = SlsaProvenance.forGitHubWorkflow(claims);
+ * ```
+ *
+ * @public
+ */
+declare class SlsaProvenance extends SlsaProvenance_base {
+  /** The predicate type URI a statement carrying this must declare. */
+  static readonly predicateType: PredicateType;
+  /** The build type this package's GitHub-workflow constructor stamps. */
+  static readonly buildType: string;
+  /**
+   * Provenance for a GitHub Actions `workflow/v1` build.
+   *
+   * @remarks
+   * **Total** — a pure projection of its argument. Every value it needs is
+   * already in the input; nothing is read from the environment and nothing can
+   * fail.
+   */
+  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 };
+//# sourceMappingURL=index.d.ts.map