python-sbom 0.1.1__py3-none-any.whl

python_sbom/_wheel/__init__.py

@@ -0,0 +1 @@
+"""Zip artifacts: one checked handle per build, verifying the wheels they bundle, and writing an SBOM in."""

python_sbom/_wheel/_bundled.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING, Final
+
+from installer.records import InvalidRecordEntry, parse_record_file
+from installer.sources import WheelFile
+from packaging.requirements import InvalidRequirement, Requirement
+
+from python_sbom._errors import SbomError
+from python_sbom._model._inputs import BundledWheel, RecordRow
+from python_sbom._model._metadata import CoreMetadata, parse_metadata
+
+from ._record import record_rows
+from ._zip import open_archive, read_member, read_wheel_metadata, sha256_hex
+
+if TYPE_CHECKING:
+    import zipfile
+    from collections.abc import Callable
+    from typing import IO
+
+
+# wheels verified at once, each perhaps in memory whole
+_WORKERS: Final[int] = 4
+
+
+def read_bundled_wheels(paths: list[str], open_wheel: Callable[[str], IO[bytes]]) -> list[BundledWheel]:
+    # inflating and hashing release the GIL, so the wheels verify side by side, a few at a time, as each may be held in
+    # memory whole; results and the first error come in the order given
+    def read(path: str) -> BundledWheel:
+        with open_wheel(path) as stream:
+            return _read_bundled_wheel(stream, path)
+
+    with ThreadPoolExecutor(max_workers=_WORKERS) as pool:
+        return list(pool.map(read, paths))
+
+
+def _read_bundled_wheel(stream: IO[bytes], path: str) -> BundledWheel:
+    where: Final[str] = f"bundled wheel {path}"
+    sha256: Final[str] = sha256_hex(stream)
+    stream.seek(0)
+    with open_archive(stream, where) as archive:
+        # installer takes the project name from the archive's file name, which an archive read from memory lacks
+        archive.filename = path
+        members: Final[list[str]] = sorted(info.filename for info in archive.infolist() if not info.is_dir())
+        wheel, metadata = read_wheel_metadata(archive, where)
+        dist_info: Final[str] = wheel.dist_info_dir
+        _check_named(metadata, where, f"{dist_info}/METADATA")
+        files: Final[list[RecordRow]] = _verified_record(archive, wheel, where)
+        vendored: Final[list[tuple[str, CoreMetadata]]] = [
+            *_vendor_manifest(archive, where, members),
+            *(
+                (name, _vendored_metadata(archive, where, name))
+                for name in members
+                if "/_vendor/" in name and name.endswith(".dist-info/METADATA")
+            ),
+        ]
+    return BundledWheel(
+        path=path,
+        sha256=sha256,
+        metadata_name=f"{dist_info}/METADATA",
+        metadata=metadata,
+        files=files,
+        vendored=vendored,
+    )
+
+
+def _check_named(metadata: CoreMetadata, where: str, name: str) -> None:
+    if not (metadata.name and metadata.version):
+        msg = f"{where}: {name} lacks Name or Version"
+        raise SbomError(msg)
+
+
+def _verified_record(archive: zipfile.ZipFile, wheel: WheelFile, where: str) -> list[RecordRow]:
+    # the SBOM copies these rows, so a RECORD that misstates the wheel would make the SBOM misstate it too
+    dist_info: Final[str] = wheel.dist_info_dir
+    # installer decompresses RECORD whole, so a capped read comes first and bounds installer's read of the same bytes
+    record: Final[str] = read_member(archive, f"{dist_info}/RECORD", where).decode("utf-8")
+    try:
+        rows: Final[list[tuple[str, str, str]]] = list(parse_record_file(record.splitlines()))
+        # read before installer's check, which takes any hashlib name and fails on one needing a length, such as
+        # shake_128, with a TypeError
+        found: Final[list[RecordRow]] = record_rows(rows, where)
+    except InvalidRecordEntry as error:
+        msg = f"{where}: RECORD does not parse: {error}"
+        raise SbomError(msg) from error
+    # installer checks the last row of a path only, skips rows naming no member, and lets a RECORD.jws or RECORD.p7s
+    # anywhere under the .dist-info, "../" included, go unlisted, so each of these checks is ours
+    if repeated := sorted(path for path, count in Counter(path for path, _, _ in rows).items() if count > 1):
+        msg = f"{where}: RECORD lists {', '.join(repeated)} more than once"
+        raise SbomError(msg)
+    members: Final[set[str]] = {info.filename for info in archive.infolist() if not info.is_dir()}
+    recorded: Final[set[str]] = {path for path, _, _ in rows}
+    # installer checks the row of RECORD itself, the one row without a digest
+    if missing := sorted(
+        members - recorded - {f"{dist_info}/{name}" for name in ("RECORD", "RECORD.jws", "RECORD.p7s")}
+    ):
+        msg = f"{where}: RECORD lacks a digest for {', '.join(missing)}"
+        raise SbomError(msg)
+    if extra := sorted(recorded - members):
+        msg = f"{where}: RECORD lists {', '.join(extra)}, which the wheel does not hold"
+        raise SbomError(msg)
+    try:
+        wheel.validate_record()
+    except WheelFile.validation_error as error:
+        # installer documents the exception class only, not the list of issues it carries
+        issues: Final[list[str]] = getattr(error, "issues", [str(error)])
+        prefix: Final[str] = f"In {archive.filename}, "
+        msg = f"{where}: RECORD disagrees with the wheel: {'; '.join(issue.removeprefix(prefix) for issue in issues)}"
+        raise SbomError(msg) from error
+    return found
+
+
+def _vendor_manifest(archive: zipfile.ZipFile, where: str, members: list[str]) -> list[tuple[str, CoreMetadata]]:
+    # pip lists what it vendors in _vendor/vendor.txt instead of shipping each vendored .dist-info
+    found: Final[list[tuple[str, CoreMetadata]]] = []
+    for name in (member for member in members if member.endswith("/_vendor/vendor.txt")):
+        for line in read_member(archive, name, where).decode("utf-8").splitlines():
+            if not (text := line.partition("#")[0].strip()):
+                continue
+            try:
+                pins = list((requirement := Requirement(text)).specifier)
+            except InvalidRequirement as error:
+                msg = f"{where}: vendored requirement in {name} does not parse: {text}"
+                raise SbomError(msg) from error
+            if len(pins) != 1 or pins[0].operator != "==" or "*" in pins[0].version:
+                msg = f"{where}: vendored requirement in {name} pins no one exact version: {text}"
+                raise SbomError(msg)
+            found.append((name, CoreMetadata(raw={"name": requirement.name, "version": pins[0].version}, unparsed={})))
+    return found
+
+
+def _vendored_metadata(archive: zipfile.ZipFile, where: str, name: str) -> CoreMetadata:
+    metadata: Final[CoreMetadata] = parse_metadata(read_member(archive, name, where).decode("utf-8"))
+    _check_named(metadata, where, name)
+    return metadata
+
+
+__all__ = [
+    "read_bundled_wheels",
+]

python_sbom/_wheel/_reader.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from io import BytesIO
+from typing import TYPE_CHECKING, Final
+
+from ._bundled import read_bundled_wheels
+from ._zip import open_archive, read_member, sha256_hex
+
+if TYPE_CHECKING:
+    import zipfile
+    from collections.abc import Generator
+    from pathlib import Path, PurePosixPath
+
+    from python_sbom._model._inputs import BundledWheel
+
+# a bundled wheel is read whole, to hash it and open it as a zip, so its size is capped as metadata's is
+_WHEEL_LIMIT: Final[int] = 512 * 1024 * 1024
+
+
+@contextmanager
+def open_artifact(path: Path) -> Generator[ArtifactReader, None, None]:
+    # one open zip serves every read of a build, the provider's included, so the archive is checked and indexed once
+    with open_archive(path, str(path)) as archive:
+        yield ArtifactReader(path=path, archive=archive, members=frozenset(archive.namelist()))
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ArtifactReader:
+    path: Path
+    archive: zipfile.ZipFile
+    members: frozenset[str]
+
+    def digest(self, name: str) -> str:
+        with self.archive.open(name) as member:
+            return sha256_hex(member)
+
+    def provider_read(self, path: PurePosixPath) -> bytes:
+        # a provider asking for a member the artifact lacks gets the KeyError a mapping raises, which it may expect
+        if (name := str(path)) not in self.members:
+            raise KeyError(name)
+        return self.read(name)
+
+    def read(self, name: str) -> bytes:
+        return read_member(self.archive, name, str(self.path))
+
+    def bundled_wheels(self, names: list[str]) -> list[BundledWheel]:
+        # zipfile serializes the seeks of concurrent member reads on its own lock, so the verifying threads share this
+        # handle and inflate side by side
+        return read_bundled_wheels(
+            names, lambda name: BytesIO(read_member(self.archive, name, str(self.path), _WHEEL_LIMIT))
+        )
+
+
+__all__ = [
+    "ArtifactReader",
+    "open_artifact",
+]

python_sbom/_wheel/_record.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import base64
+import binascii
+from itertools import starmap
+from typing import TYPE_CHECKING, Final
+
+from installer.records import RecordEntry
+
+from python_sbom._errors import SbomError
+from python_sbom._model._inputs import RecordRow
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# the algorithms a wheel RECORD may name, as CycloneDX spells them
+_ALGORITHMS: Final[dict[str, str]] = {
+    "md5": "MD5",
+    "sha1": "SHA-1",
+    "sha256": "SHA-256",
+    "sha384": "SHA-384",
+    "sha512": "SHA-512",
+}
+
+
+def record_rows(rows: Iterable[tuple[str, str, str]], where: str) -> list[RecordRow]:
+    # the rows with a digest, as the SBOM lists them: RECORD's own row has none, nor has a file an installer left
+    # unhashed; installer's InvalidRecordEntry passes to the caller, which knows what a malformed row means there
+    found: Final[list[RecordRow]] = []
+    for entry in starmap(RecordEntry.from_elements, rows):
+        if entry.hash_ is None:
+            continue
+        algorithm, digest = _decode_digest(str(entry.hash_), f"{where}: RECORD row for {entry.path}")
+        found.append(RecordRow(path=entry.path, algorithm=algorithm, digest=digest, size=str(entry.size)))
+    return found
+
+
+def _decode_digest(digest: str, where: str) -> tuple[str, str]:
+    # installer checks RECORD digests as urlsafe base64 under any hashlib name, while CycloneDX takes hex under its own
+    # names for a few algorithms
+    name, _, encoded = digest.partition("=")
+    if (algorithm := _ALGORITHMS.get(name)) is None:
+        msg = f"{where}: unknown hash algorithm {name!r}"
+        raise SbomError(msg)
+    try:
+        raw = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
+    except binascii.Error as error:
+        msg = f"{where}: digest {encoded!r} is not urlsafe base64"
+        raise SbomError(msg) from error
+    return algorithm, raw.hex()
+
+
+__all__ = [
+    "record_rows",
+]

python_sbom/_wheel/_write.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import csv
+import os
+import shutil
+import stat
+import tempfile
+import time
+import zipfile
+from io import BytesIO, StringIO
+from pathlib import Path
+from typing import Final
+
+import zipremove
+from installer.records import Hash, RecordEntry
+from installer.utils import copyfileobj_with_hashing
+
+from python_sbom._errors import SbomError
+
+from ._zip import open_archive, wheel_source
+
+# 1980-01-01, the earliest time a zip entry holds
+_ZIP_EPOCH: Final[int] = 315532800
+
+
+def write_sbom(wheel: Path, name: str, content: bytes, epoch: int) -> str:
+    with open_archive(wheel, str(wheel)) as archive:
+        _, dist_info = wheel_source(archive, str(wheel))
+        record: Final[str] = f"{dist_info}/RECORD"
+        if missing := sorted({f"{dist_info}/METADATA", record} - set(archive.namelist())):
+            msg = f"{wheel} has no {', '.join(missing)}"
+            raise SbomError(msg)
+        record_info: Final[zipfile.ZipInfo] = archive.getinfo(record)
+        record_data: Final[bytes] = archive.read(record_info)
+    sbom: Final[str] = f"{dist_info}/sboms/{name}"
+    entry: Final[zipfile.ZipInfo] = _entry(sbom, epoch)
+    entry.compress_type = zipfile.ZIP_DEFLATED
+    rewritten: Final[bytes] = _rewritten_record(record_data, record, sbom, content)
+    # a name no "dist/*.whl" glob matches, in the wheel's directory so the final rename stays on one file system
+    descriptor, temporary = tempfile.mkstemp(dir=wheel.parent, prefix=".python-sbom-", suffix=".tmp")
+    os.close(descriptor)
+    try:  # ruff: ignore[too-many-statements-in-try-clause] # whichever step fails, the temporary file goes
+        # copied through the process: copy_file_range makes some file systems first flush the wheel just written
+        with wheel.open("rb") as source, Path(temporary).open("wb") as target:
+            shutil.copyfileobj(source, target)
+        # the other members keep their bytes as stored, still compressed, so only the SBOM and RECORD get compressed
+        # here; both go last, RECORD after the SBOM
+        with zipremove.ZipFile(temporary, "a") as archive:
+            stale = [info for info in archive.infolist() if info.filename in {record, sbom}]
+            archive.repack(list(map(archive.remove, stale)))  # ty: ignore[unresolved-attribute] # zipremove adds both
+            archive.writestr(entry, content)
+            archive.writestr(record_info, rewritten)
+        Path(temporary).chmod(stat.S_IMODE(wheel.stat().st_mode))
+        Path(temporary).replace(wheel)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+    return sbom
+
+
+def _entry(name: str, epoch: int) -> zipfile.ZipInfo:
+    # zip times start at 1980; Unix attributes whichever system writes the entry, so the bytes match across systems
+    entry: Final[zipfile.ZipInfo] = zipfile.ZipInfo(name, time.gmtime(max(epoch, _ZIP_EPOCH))[:6])
+    entry.create_system = 3
+    entry.external_attr = (stat.S_IFREG | 0o644) << 16
+    return entry
+
+
+def _rewritten_record(record: bytes, name: str, sbom: str, content: bytes) -> bytes:
+    lines: Final[list[str]] = [line for line in record.decode("utf-8").splitlines(keepends=True) if _path(line) != sbom]
+    newline: Final[str] = "\r\n" if lines and lines[0].endswith("\r\n") else "\n"
+    # a last row without its line end would take the SBOM's row onto its own line
+    if lines and not lines[-1].endswith(("\n", "\r")):
+        lines[-1] += newline
+    # the row of RECORD itself stays last
+    at: Final[int] = next((index for index, line in enumerate(lines) if _path(line) == name), len(lines))
+    # installer's helper hashes as it copies; the copy is thrown away
+    digest, size = copyfileobj_with_hashing(BytesIO(content), BytesIO(), "sha256")
+    row: Final[StringIO] = StringIO()
+    csv.writer(row, lineterminator=newline).writerow(RecordEntry(sbom, Hash("sha256", digest), size).to_row())
+    lines.insert(at, row.getvalue())
+    return "".join(lines).encode()
+
+
+def _path(line: str) -> str:
+    # RECORD quotes a path that holds a comma, a quote or a line end, so the raw start of a line misses its row
+    return next(csv.reader([line]), [""])[0]
+
+
+def append_member(archive: Path, name: str, content: bytes, epoch: int) -> None:
+    with zipfile.ZipFile(archive, "a") as handle:
+        if name in handle.namelist():
+            msg = f"{archive.name} already holds {name}"
+            raise SbomError(msg)
+        # deflated at the highest level whatever the other members use, since a zipapp may store them all and the SBOM
+        # then adds megabytes; a fixed level, time and attributes keep the bytes the same for one input on every system
+        handle.writestr(_entry(name, epoch), content, compress_type=zipfile.ZIP_DEFLATED, compresslevel=9)
+
+
+__all__ = [
+    "append_member",
+    "write_sbom",
+]

python_sbom/_wheel/_zip.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import hashlib
+import zipfile
+import zlib
+from collections import Counter
+from contextlib import contextmanager
+from typing import IO, TYPE_CHECKING, Final
+
+from installer.sources import WheelFile
+
+from python_sbom._errors import SbomError
+from python_sbom._model._metadata import CoreMetadata, parse_metadata
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from pathlib import Path
+
+# metadata files beyond this size are refused, so a hostile wheel cannot exhaust memory
+_METADATA_LIMIT: Final[int] = 16 * 1024 * 1024
+# members inflate a chunk at a time, so a size the archive states falsely is caught before it is all in memory
+CHUNK: Final[int] = 1024 * 1024
+
+
+@contextmanager
+def open_archive(file: Path | IO[bytes], where: str) -> Generator[zipfile.ZipFile, None, None]:
+    try:
+        with zipfile.ZipFile(file) as archive:
+            # installers extract the first of two same-named members and zipfile reads the last, and a file system that
+            # ignores case merges names that differ only by case, so such names would hide what gets installed;
+            # installer's WheelFile accepts names that differ only by case
+            if clashes := sorted(
+                name for name, count in Counter(name.casefold() for name in archive.namelist()).items() if count > 1
+            ):
+                msg = f"{where} holds more than one member named {', '.join(clashes)}, ignoring case"
+                raise SbomError(msg)
+            yield archive
+    # zipfile raises these as late as a member's last read, inside installer's checks too, which let them through
+    except (zipfile.BadZipFile, zlib.error) as error:
+        msg = f"{where} is not a valid zip archive: {error}"
+        raise SbomError(msg) from error
+
+
+def read_wheel_metadata(archive: zipfile.ZipFile, where: str) -> tuple[WheelFile, CoreMetadata]:
+    wheel, dist_info = wheel_source(archive, where)
+    # read capped, as installer's read_dist_info decompresses the member whole
+    return wheel, parse_metadata(read_member(archive, f"{dist_info}/METADATA", where).decode("utf-8"))
+
+
+def wheel_source(archive: zipfile.ZipFile, where: str) -> tuple[WheelFile, str]:
+    # installer refuses a wheel whose file name does not parse, or that holds other than one top-level .dist-info, since
+    # a second one is a decoy that could decide whose metadata counts
+    try:
+        wheel = WheelFile(archive)
+        dist_info = wheel.dist_info_dir
+    except ValueError as error:
+        msg = f"{where} is not a wheel: {error}"
+        raise SbomError(msg) from error
+    return wheel, dist_info
+
+
+def read_member(archive: zipfile.ZipFile, name: str, where: str, limit: int = _METADATA_LIMIT) -> bytes:
+    try:
+        info = archive.getinfo(name)
+    except KeyError as error:
+        msg = f"{where} has no {name}"
+        raise SbomError(msg) from error
+    # counted as it decompresses, since the size the archive states may lie and one read decompresses it all at once
+    content: Final[bytearray] = bytearray()
+    with archive.open(info) as member:
+        while chunk := member.read(CHUNK):
+            content.extend(chunk)
+            if len(content) > limit:
+                msg = f"{where}: {name} is over the {limit} byte limit"
+                raise SbomError(msg)
+    return bytes(content)
+
+
+def sha256_hex(stream: IO[bytes]) -> str:
+    # hashlib.file_digest wants readinto, which a zip member stream typed as IO[bytes] does not promise
+    digest: Final = hashlib.sha256()
+    while chunk := stream.read(CHUNK):
+        digest.update(chunk)
+    return digest.hexdigest()
+
+
+__all__ = [
+    "CHUNK",
+    "open_archive",
+    "read_member",
+    "read_wheel_metadata",
+    "sha256_hex",
+    "wheel_source",
+]

python_sbom/hatch/__init__.py

@@ -0,0 +1,9 @@
+"""The hatchling build hook, which writes the SBOM into every wheel hatchling builds."""
+
+from __future__ import annotations
+
+from ._hook import SbomBuildHook
+
+__all__ = [
+    "SbomBuildHook",
+]

python_sbom/hatch/_hook.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+import weakref
+from functools import cached_property
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Any, Final
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from hatchling.builders.utils import get_reproducible_timestamp
+from hatchling.utils.constants import DEFAULT_BUILD_SCRIPT
+
+from python_sbom._collect._content import resolve_provider
+from python_sbom._collect._revision import REVISION_FILE, default_revision
+from python_sbom._collect._settings import settings_from_table
+from python_sbom._errors import SbomError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from python_sbom._model._content import ContentProvider
+    from python_sbom._model._inputs import Settings
+
+# options of every hatchling hook table, which hatchling itself reads
+_HATCHLING_OPTIONS: Final[frozenset[str]] = frozenset({
+    "dependencies",
+    "enable-by-default",
+    "path",
+    "require-runtime-dependencies",
+    "require-runtime-features",
+})
+
+
+class SbomBuildHook(BuildHookInterface):
+    """
+    Hatchling build hook that writes a CycloneDX SBOM into the wheel's ``.dist-info/sboms/``, as PEP 770 describes.
+
+    It runs once hatchling has written the wheel, so the SBOM describes the wheel's final metadata and file name
+    whatever other hooks changed. Options come from ``[tool.python-sbom]``, the one place ``python-sbom embed`` and
+    ``python-sbom archive`` read them too. For an sdist it records the source revision, so a wheel built from that sdist
+    still names its commit.
+
+    :cvar PLUGIN_NAME: the hook's name in ``[tool.hatch.build.hooks]``
+
+    """
+
+    PLUGIN_NAME = "python-sbom"
+    _remove_revision_file: Callable[[], None] | None = None
+
+    def initialize(
+        self,
+        version: str,
+        build_data: dict[str, Any],  # simplint: ignore[SMP602] # hatchling's signature
+    ) -> None:
+        """
+        Read the source revision, and record it in an sdist.
+
+        :param version: hatchling's build variant
+        :param build_data: hatchling's build data, which receives the revision file
+
+        """
+        if self.target_name not in {"sdist", "wheel"} or version == "editable":
+            return
+        # once per build, before it writes the artifact into a checkout that may not ignore it; a value kept for the
+        # process would name an older commit in the next build after a commit
+        self._revision = revision = default_revision(Path(self.root))
+        # a dirty checkout has no commit that reproduces the sdist, so a wheel built from it names none
+        if self.target_name != "sdist" or revision is None or revision.dirty:
+            return
+        # outside the project, so the build leaves nothing behind in it
+        directory = tempfile.mkdtemp()
+        # hatchling reads the file only while it writes the sdist, and skips finalize when the build fails, so the
+        # directory then goes with the hook, at the latest when the interpreter exits
+        self._remove_revision_file = weakref.finalize(self, shutil.rmtree, directory)
+        # bytes, so the sdist holds the same LF line on every OS
+        (written := Path(directory) / REVISION_FILE).write_bytes(f"node: {revision.commit}\n".encode())
+        build_data["force_include"][str(written)] = REVISION_FILE
+
+    def finalize(
+        self,
+        version: str,
+        build_data: (  # ruff: ignore[unused-method-argument] # hatchling's signature
+            dict[str, Any]  # simplint: ignore[SMP602] # see above
+        ),
+        artifact_path: str,
+    ) -> None:
+        """
+        Write the SBOM into the wheel hatchling built, and remove the revision file an sdist build wrote.
+
+        :param version: hatchling's build variant; an editable wheel gets no SBOM, since it carries no code
+        :param build_data: hatchling's build data
+        :param artifact_path: the built wheel
+
+        """
+        if self._remove_revision_file is not None:
+            self._remove_revision_file()
+        if self.target_name != "wheel" or version == "editable":
+            return
+        # what a wheel needs loads only when one is built, so an sdist build stays light
+        from python_sbom._collect._facts import collect_facts  # ruff: ignore[import-outside-top-level] # see above
+        from python_sbom._generate._embed import embed_into  # ruff: ignore[import-outside-top-level] # see above
+
+        root = Path(self.root)
+        # content_provider() may be a subclass's override, so its result goes through resolve_provider again, which
+        # returns a given instance as is, for the provider's source files to be listed among the build tools
+        content, provider_scripts = resolve_provider(self.content_provider(), self._settings, root)
+        # a custom hook script shapes the document, as a provider defined in the project does, so the SBOM lists both
+        # among the build tools
+        own = [PurePosixPath(self.config.get("path", DEFAULT_BUILD_SCRIPT))] if self.PLUGIN_NAME == "custom" else []
+        scripts = tuple(dict.fromkeys([*own, *provider_scripts]))
+        # hatchling's own fixed time for a reproducible build when SOURCE_DATE_EPOCH is unset, so the SBOM agrees with
+        # the zip entries hatchling wrote
+        facts = collect_facts(
+            root,
+            lambda _root: self._revision,
+            default_epoch=get_reproducible_timestamp() if self.build_config.reproducible else None,
+        )
+        embed_into(
+            Path(artifact_path), root, settings=self._settings, content=content, build_scripts=scripts, facts=facts
+        )
+
+    def content_provider(self) -> ContentProvider:
+        """
+        Return what the project adds to its SBOM.
+
+        Override it in a hatchling custom build hook to build the provider with what the hook knows; the
+        ``content-provider`` option is then ignored.
+
+        :returns: the ``content-provider`` option's provider, or one that adds nothing
+
+        """
+        return resolve_provider(None, self._settings, Path(self.root))[0]
+
+    @cached_property
+    def _settings(self) -> Settings:
+        # hatchling has parsed pyproject.toml already; the hook's own table holds only hatchling's options, so every
+        # entry point reads the same [tool.python-sbom]
+        if unknown := sorted(self.config.keys() - _HATCHLING_OPTIONS):
+            msg = (
+                f"the {self.PLUGIN_NAME} hook's table holds {', '.join(unknown)}; move python-sbom's options to"
+                " [tool.python-sbom], where python-sbom embed and python-sbom archive read them too"
+            )
+            raise SbomError(msg)
+        return settings_from_table(self.metadata.config.get("tool", {}).get("python-sbom", {}), "[tool.python-sbom]")
+
+
+__all__ = [
+    "SbomBuildHook",
+]

python_sbom/hatch/hooks.py

@@ -0,0 +1,18 @@
+"""Register the build hook with hatchling."""
+
+from __future__ import annotations
+
+from hatchling.plugin import hookimpl
+
+from ._hook import SbomBuildHook
+
+
+@hookimpl
+def hatch_register_build_hook() -> type[SbomBuildHook]:
+    """
+    Return the build hook hatchling loads for ``[tool.hatch.build.hooks.python-sbom]``.
+
+    :returns: the build hook class
+
+    """
+    return SbomBuildHook

python_sbom/version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None