@effected/sbom 0.1.0

package/IdentityToken.js

@@ -0,0 +1,65 @@
+import { Context, Effect, Layer, Redacted, Schema } from "effect";
+
+//#region src/IdentityToken.ts
+/**
+* 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
+*/
+var IdentityTokenError = class extends Schema.TaggedErrorClass()("IdentityTokenError", {
+	/** The audience the token was requested for. */
+	audience: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Could not obtain an identity token for the "${this.audience}" audience`;
+	}
+};
+/** The token every double answers with unless a test says otherwise. */
+const TEST_TOKEN = "test-identity-token";
+/**
+* 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
+*/
+var IdentityToken = class IdentityToken extends Context.Service()("@effected/sbom/IdentityToken") {
+	/**
+	* 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 layerStatic = (token) => Layer.succeed(IdentityToken, { token: () => Effect.succeed(typeof token === "string" ? Redacted.make(token) : token) });
+	/**
+	* 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 makeTest = (overrides = {}) => ({ token: overrides.token ?? (() => Effect.succeed(Redacted.make(TEST_TOKEN))) });
+	/** {@link (IdentityToken:class).makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(IdentityToken, IdentityToken.makeTest(overrides));
+};
+
+//#endregion
+export { IdentityToken, IdentityTokenError };

package/InTotoStatement.js

@@ -0,0 +1,159 @@
+import { Effect, Result, Schema } from "effect";
+
+//#region src/InTotoStatement.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
+*/
+const IN_TOTO_STATEMENT_V1 = "https://in-toto.io/Statement/v1";
+/**
+* The CycloneDX BOM predicate type, for attesting an SBOM.
+*
+* @public
+*/
+const CYCLONEDX_BOM_PREDICATE = "https://cyclonedx.org/bom";
+/**
+* Raised when a string is not a SHA-256 digest.
+*
+* @public
+*/
+var InvalidSha256DigestError = class extends Schema.TaggedErrorClass()("InvalidSha256DigestError", { 
+/** The offending input, preserved verbatim. */
+input: Schema.String }) {
+	get message() {
+		return `Invalid SHA-256 digest "${this.input}": expected 64 hexadecimal characters`;
+	}
+};
+/** 64 hex characters, lowercase — the normalized form. */
+const SHA256_RE = /^[0-9a-f]{64}$/;
+/** The `sha256:` prefix a caller may have carried in from a digest reference. */
+const SHA256_PREFIX_RE = /^sha256:/i;
+const normalizeDigest = (value) => value.replace(SHA256_PREFIX_RE, "").toLowerCase();
+const parseResult = (value) => {
+	const normalized = normalizeDigest(value);
+	return SHA256_RE.test(normalized) ? Result.succeed(normalized) : Result.fail(new InvalidSha256DigestError({ input: value }));
+};
+/**
+* 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
+*/
+const Sha256Digest = Object.assign(Schema.String.pipe(Schema.check(Schema.isPattern(SHA256_RE)), Schema.brand("Sha256Digest")), {
+	isValid: (value) => SHA256_RE.test(normalizeDigest(value)),
+	parseResult,
+	parse: Effect.fn("Sha256Digest.parse")((value) => Effect.fromResult(parseResult(value)))
+});
+/**
+* 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
+*/
+var InTotoSubject = class InTotoSubject extends Schema.Class("InTotoSubject")({
+	/** How the subject is identified — a purl for an npm package. */
+	name: Schema.String,
+	/** Algorithm to hex digest. */
+	digest: Schema.Record(Schema.String, Schema.String)
+}) {
+	/**
+	* 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, digest) {
+		return InTotoSubject.make({
+			name,
+			digest: { sha256: digest }
+		});
+	}
+};
+/**
+* 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
+*/
+var InTotoStatement = class InTotoStatement extends Schema.Class("InTotoStatement")({
+	/** Always the in-toto Statement v1 URI. */
+	_type: Schema.Literal(IN_TOTO_STATEMENT_V1),
+	/** The artifacts attested. */
+	subject: Schema.Array(InTotoSubject),
+	/** What is being asserted about them. */
+	predicateType: Schema.String,
+	/** The assertion body. */
+	predicate: Schema.Unknown
+}) {
+	/** A statement over any number of subjects. **Total.** */
+	static of(input) {
+		return InTotoStatement.make({
+			_type: IN_TOTO_STATEMENT_V1,
+			subject: input.subject,
+			predicateType: input.predicateType,
+			predicate: input.predicate
+		});
+	}
+	/** A statement over a single artifact — the common case. **Total.** */
+	static forSubject(input) {
+		return InTotoStatement.of({
+			subject: [InTotoSubject.forSha256(input.name, input.digest)],
+			predicateType: input.predicateType,
+			predicate: input.predicate
+		});
+	}
+	/**
+	* 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) {
+		return JSON.stringify({
+			_type: this._type,
+			subject: this.subject.map((subject) => ({
+				name: subject.name,
+				digest: subject.digest
+			})),
+			predicateType: this.predicateType,
+			predicate: this.predicate
+		}, null, options?.space ?? 0);
+	}
+};
+
+//#endregion
+export { CYCLONEDX_BOM_PREDICATE, IN_TOTO_STATEMENT_V1, InTotoStatement, InTotoSubject, InvalidSha256DigestError, Sha256Digest };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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/NtiaReport.js

@@ -0,0 +1,142 @@
+import { Schema } from "effect";
+
+//#region src/NtiaReport.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
+*/
+const NtiaElementId = Schema.Literals([
+	"supplierName",
+	"componentName",
+	"componentVersion",
+	"uniqueIdentifier",
+	"dependencyRelationship",
+	"sbomAuthor",
+	"timestamp"
+]);
+/**
+* One element's verdict.
+*
+* @public
+*/
+var NtiaElement = class extends Schema.Class("NtiaElement")({
+	/** Which element this is. */
+	id: NtiaElementId,
+	/** Whether the document satisfies it. */
+	satisfied: Schema.Boolean,
+	/** The value that satisfied it, when one did. */
+	value: Schema.optionalKey(Schema.String)
+}) {};
+const element = (id, value) => NtiaElement.make({
+	id,
+	satisfied: value !== void 0,
+	...value !== void 0 && { value }
+});
+/** A string that carries something, or nothing. */
+const present = (value) => {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+};
+/** Element 1: the entity that supplies the software. */
+const supplierName = (document) => element("supplierName", present(document.metadata?.supplier?.name));
+/** Element 2: what the software is called. */
+const componentName = (document) => element("componentName", present(document.metadata?.component?.name));
+/** Element 3: which release it is. */
+const componentVersion = (document) => element("componentVersion", present(document.metadata?.component?.version));
+/**
+* Element 4: an identifier that is unique across suppliers — a package URL.
+*
+* Present-and-non-empty is not enough: a homepage URL in the `purl` field is a
+* string, and identifies the component to nobody.
+*/
+const uniqueIdentifier = (document) => {
+	const purl = present(document.metadata?.component?.purl);
+	return element("uniqueIdentifier", purl?.startsWith("pkg:") === true ? purl : void 0);
+};
+/**
+* Element 5: how the components relate to the thing the BOM is about.
+*
+* A flat component list plus a declared root IS that relationship in this
+* version — the CycloneDX `dependencies` graph is deferred until a consumer
+* needs one. What the element therefore requires is a declared **subject**: a
+* list of components with nothing saying what they are components OF relates
+* nothing to anything.
+*
+* An empty list is compliant. "This package has no dependencies" is an
+* assertion, not a gap.
+*/
+const dependencyRelationship = (document) => {
+	const count = document.components.length;
+	return element("dependencyRelationship", document.metadata?.component === void 0 ? void 0 : `${count} component${count === 1 ? "" : "s"}`);
+};
+/**
+* Element 6: who assembled the BOM.
+*
+* Named authors first; a supplier or a publisher is the honest fallback, since
+* both identify an entity that stood behind the document.
+*/
+const sbomAuthor = (document) => {
+	const author = document.metadata?.authors?.map((contact) => present(contact.name)).find((name) => name !== void 0);
+	const supplier = present(document.metadata?.supplier?.name);
+	const publisher = present(document.metadata?.component?.publisher);
+	return element("sbomAuthor", author ?? supplier ?? publisher);
+};
+/**
+* Element 7: when the BOM was assembled.
+*
+* Parsed, not merely present — a field holding `last tuesday` records nothing,
+* and this is the cheapest place to notice.
+*/
+const timestamp = (document) => {
+	const stamped = present(document.metadata?.timestamp);
+	return element("timestamp", stamped !== void 0 && !Number.isNaN(Date.parse(stamped)) ? stamped : void 0);
+};
+/**
+* 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
+*/
+var NtiaReport = class NtiaReport extends Schema.Class("NtiaReport")({ 
+/** One verdict per element, in the published order. */
+elements: Schema.Array(NtiaElement) }) {
+	/** Whether every element is satisfied. */
+	get compliant() {
+		return this.elements.every((entry) => entry.satisfied);
+	}
+	/** The elements the document does not satisfy, by id. */
+	get missing() {
+		return this.elements.filter((entry) => !entry.satisfied).map((entry) => entry.id);
+	}
+	/**
+	* Check a document. **Total** — a report is the answer for every input,
+	* including a document that satisfies nothing.
+	*/
+	static of(document) {
+		return NtiaReport.make({ elements: [
+			supplierName(document),
+			componentName(document),
+			componentVersion(document),
+			uniqueIdentifier(document),
+			dependencyRelationship(document),
+			sbomAuthor(document),
+			timestamp(document)
+		] });
+	}
+};
+
+//#endregion
+export { NtiaElement, NtiaElementId, NtiaReport };

package/Sbom.js

@@ -0,0 +1,100 @@
+import { BOM_FORMAT, SbomDocument, SbomMetadata, documentJson } from "./SbomDocument.js";
+import { Effect, FileSystem, Schema } from "effect";
+
+//#region src/Sbom.ts
+/**
+* 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
+*/
+var SbomWriteError = class extends Schema.TaggedErrorClass()("SbomWriteError", {
+	/** The path that could not be written. */
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to write the SBOM to ${this.path}`;
+	}
+};
+const generate = (input) => SbomDocument.make({
+	bomFormat: BOM_FORMAT,
+	specVersion: "1.6",
+	version: 1,
+	metadata: metadataWithRoot(input),
+	components: [...input.components].sort((a, b) => a.name.localeCompare(b.name))
+});
+/**
+* Thread the root component onto the caller's metadata, or synthesize metadata
+* carrying it.
+*
+* Rebuilt through `SbomMetadata.make` rather than spread into a plain object:
+* a spread of a `Schema.Class` instance loses its prototype, and a plain object
+* standing in for a class field is the kind of lie that works until something
+* asks whether it is an instance. The conditional spreads are required by
+* `exactOptionalPropertyTypes` — an explicit `undefined` does not satisfy an
+* `optionalKey` field.
+*/
+const metadataWithRoot = (input) => SbomMetadata.make({
+	component: input.root,
+	...input.metadata?.timestamp !== void 0 && { timestamp: input.metadata.timestamp },
+	...input.metadata?.authors !== void 0 && { authors: input.metadata.authors },
+	...input.metadata?.supplier !== void 0 && { supplier: input.metadata.supplier }
+});
+const toJson = (document, options) => JSON.stringify(documentJson(document), null, options?.space ?? 2);
+const write = Effect.fn("Sbom.write")(function* (document, path, options) {
+	yield* (yield* FileSystem.FileSystem).writeFileString(path, toJson(document, options)).pipe(Effect.mapError((cause) => new SbomWriteError({
+		path,
+		cause
+	})));
+});
+/**
+* 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
+*/
+var Sbom = class {
+	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 generate = generate;
+	/**
+	* 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 toJson = toJson;
+	/**
+	* 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 write = write;
+};
+
+//#endregion
+export { Sbom, SbomWriteError };